From 55944e5e40b1be2afc4855d8d2baf4b73d1876b5 Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Wed, 10 Apr 2024 22:49:52 +0200 Subject: Adding upstream version 255.4. Signed-off-by: Daniel Baumann --- man/sd_journal_add_match.xml | 185 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 185 insertions(+) create mode 100644 man/sd_journal_add_match.xml (limited to 'man/sd_journal_add_match.xml') diff --git a/man/sd_journal_add_match.xml b/man/sd_journal_add_match.xml new file mode 100644 index 0000000..5329498 --- /dev/null +++ b/man/sd_journal_add_match.xml @@ -0,0 +1,185 @@ + + + + + + + + sd_journal_add_match + systemd + + + + sd_journal_add_match + 3 + + + + sd_journal_add_match + sd_journal_add_disjunction + sd_journal_add_conjunction + 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_add_conjunction + sd_journal *j + + + + void 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. + Parameter data must be 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 anything, including binary. Parameter + size specifies the number of bytes in data + (i.e. the length of FIELD, plus one, plus the length of + value). Parameter size may also be + specified as 0, in which case data + must be a NUL-terminated string, and the bytes before the terminating + zero are used as the match. + + 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 since the + last invocation of + sd_journal_add_disjunction() or + sd_journal_add_conjunction() are combined in + an OR with all matches added afterwards, until + sd_journal_add_disjunction() or + sd_journal_add_conjunction() is invoked again + to begin the next OR or AND term. + + sd_journal_add_conjunction() may be + used to insert a conjunction (i.e. logical AND) in the match list. + If this call is invoked, all previously added matches since the + last invocation of + sd_journal_add_conjunction() are combined in + an AND with all matches added afterwards, until + sd_journal_add_conjunction() is invoked again + to begin the next AND term. The combination of + sd_journal_add_match(), + sd_journal_add_disjunction() and + sd_journal_add_conjunction() may be used to + build complex search terms, even though full logical expressions + are not available. Note that + sd_journal_add_conjunction() operates one + level 'higher' than + sd_journal_add_disjunction(). It is hence + possible to build an expression of AND terms, consisting of OR + terms, consisting of AND terms, consisting of OR terms of matches + (the latter OR expression is implicitly created for matches with + the same field name, see above). + + sd_journal_flush_matches() may be used + to flush all matches, disjunction and conjunction 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 the way the + journal is read, it has no effect on storage on disk. + + + + Return Value + + sd_journal_add_match(), + sd_journal_add_disjunction() and + sd_journal_add_conjunction() + return 0 on success or a negative errno-style error + code. sd_journal_flush_matches() + returns nothing. + + + + + + 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", 0); + sd_journal_add_match(j, "PRIORITY=0", 0); + sd_journal_add_match(j, "PRIORITY=1", 0); + sd_journal_add_match(j, "PRIORITY=2", 0); + sd_journal_add_match(j, "PRIORITY=3", 0); + sd_journal_add_disjunction(j); + sd_journal_add_match(j, "MESSAGE_ID=03bb1dab98ab4ecfbf6fff2738bdd964", 0); +} + + + + History + sd_journal_add_match(), + sd_journal_add_disjunction(), and + sd_journal_flush_matches() were added in version 187. + sd_journal_add_conjunction() was added in version 202. + + + + See Also + + + systemd1, + sd-journal3, + sd_journal_open3, + sd_journal_next3, + sd_journal_get_data3, + systemd.journal-fields7 + + + + -- cgit v1.2.3