From f4e761c4fc7fb43040d3ac66825fe02c33564592 Mon Sep 17 00:00:00 2001 From: Lennart Poettering Date: Fri, 13 Jul 2012 22:18:17 +0200 Subject: [PATCH] man: document sd_journal_add_match() --- Makefile.am | 9 +- man/sd_journal_add_match.xml | 189 +++++++++++++++++++++++++++++++++++ 2 files changed, 196 insertions(+), 2 deletions(-) create mode 100644 man/sd_journal_add_match.xml diff --git a/Makefile.am b/Makefile.am index 73d603443..b9353f07b 100644 --- a/Makefile.am +++ b/Makefile.am @@ -507,7 +507,8 @@ MANPAGES = \ man/sd_journal_get_realtime_usec.3 \ man/sd_journal_get_cutoff_realtime_usec.3 \ man/sd_journal_get_cursor.3 \ - man/sd_journal_get_fd.3 + man/sd_journal_get_fd.3 \ + man/sd_journal_add_match.3 MANPAGES_ALIAS = \ man/reboot.8 \ @@ -561,7 +562,9 @@ MANPAGES_ALIAS = \ man/sd_journal_get_monotonic_usec.3 \ man/sd_journal_get_cutoff_monotonic_usec.3 \ man/sd_journal_process.3 \ - man/sd_journal_wait.3 + man/sd_journal_wait.3 \ + man/sd_journal_add_disjunction.3 \ + man/sd_journal_flush_matches.3 man/reboot.8: man/halt.8 man/poweroff.8: man/halt.8 @@ -615,6 +618,8 @@ man/sd_journal_get_monotonic_usec.3: man/sd_journal_get_realtime_usec.3 man/sd_journal_get_cutoff_monotonic_usec.3: man/sd_journal_get_cutoff_realtime_usec.3 man/sd_journal_process.3: man/sd_journal_get_fd.3 man/sd_journal_wait.3: man/sd_journal_get_fd.3 +man/sd_journal_add_disjunction.3: man/sd_journal_add_match.3 +man/sd_journal_flush_matches.3: man/sd_journal_add_match.3 XML_FILES = \ ${patsubst %.1,%.xml,${patsubst %.3,%.xml,${patsubst %.5,%.xml,${patsubst %.7,%.xml,${patsubst %.8,%.xml,$(MANPAGES)}}}}} diff --git a/man/sd_journal_add_match.xml b/man/sd_journal_add_match.xml new file mode 100644 index 000000000..4aadf6cf0 --- /dev/null +++ b/man/sd_journal_add_match.xml @@ -0,0 +1,189 @@ + + + + + + + + + sd_journal_add_match + systemd + + + + Developer + Lennart + Poettering + lennart@poettering.net + + + + + + sd_journal_add_match + 3 + + + + sd_journal_add_match + sd_journal_add_disjunction + sd_journal_flush_matches + Add or remove entry matches + + + + + #include <systemd/sd-journal.h> + + + int sd_journal_add_match + sd_journal* j + const void* data + size_t size + + + + int sd_journal_add_disjunction + sd_journal* j + + + + int sd_journal_flush_matches + sd_journal* j + + + + + + Description + + sd_journal_add_match() adds + a match by which to filter the entries of the journal + file. Matches applied with this call will filter what + can be iterated through and read from the journal file + via calls like + sd_journal_next3 + and + sd_journal_get_data3. Matches + are of the form FIELD=value, where + the field part is a short uppercase string consisting + only of 0-9, A-Z and the underscore. It may not begin + with two underscores or be the empty string. The value + part may be any value, including binary. If a match is + applied only entries with this field set will be + iterated. Multiple matches may be active at the same + time: if they apply to different fields only entries + with both fields set like this will be iterated, if + they apply to the same fields only entries where the + field takes one of the specified values will be + iterated. Well known fields are documented in + systemd.journal-fields7. Whenever + a new match is added the current entry position is + reset, and + sd_journal_next3 (or a similar call) + needs to be called before entries can be read + again. + + sd_journal_add_disjunction() + may be used to insert a disjunction (i.e. logical OR) + in the match list. If this call is invoked all + previously added matches are combined in an OR with + all matches added afterwards, until + sd_journal_add_disjunction() is + invoked again to begin the next OR term. The + combination of + sd_journal_add_match() and + sd_journal_add_disjunction() may + be used to build complex search terms, even though + full logical expressions are not available. + + sd_journal_flush_matches() + may be used to flush all matches and disjunction terms + again. After this call all filtering is removed and + all entries in the journal will be iterated + again. + + Note that filtering via matches only applies to + way the journal is read, it has no effect on storage + on disk. + + + + Return Value + + sd_journal_add_match() and + sd_journal_add_disjunction() + return 0 on success or a negative errno-style error + code. sd_journal_flush_matches() + returns nothing. + + + + Notes + + The sd_journal_add_match(), + sd_journal_add_disjunction() and + sd_journal_flush_matches() interfaces are + available as shared library, which can be compiled and + linked to with the + libsystemd-journal + pkg-config1 + file. + + + + Examples + + The following example adds matches to a journal + context object to iterate only through messages + generated by the Avahi service at the four error log + levels, plus all messages of the message ID + 03bb1dab98ab4ecfbf6fff2738bdd964 coming from any + service (this example lacks the necessary error + checking): + + ... +int add_matches(sd_journal *j) { + sd_journal_add_match(j, "_SYSTEMD_UNIT=avahi-daemon.service"); + sd_journal_add_match(j, "PRIORITY=0"); + sd_journal_add_match(j, "PRIORITY=1"); + sd_journal_add_match(j, "PRIORITY=2"); + sd_journal_add_match(j, "PRIORITY=3"); + sd_journal_add_disjunction(j); + sd_journal_add_match(j, "MESSAGE_ID=03bb1dab98ab4ecfbf6fff2738bdd964"); +} + + + + + See Also + + + systemd1, + sd-journal3, + sd_journal_open3, + sd_journal_next3, + sd_journal_get_data3, + systemd.journal-fields7 + + + + -- 2.30.2