X-Git-Url: http://git.ipfire.org/?a=blobdiff_plain;f=man%2Fsd_journal_add_match.xml;h=83f7fe9242d840df42a72ce586b07cf84dd72023;hb=5057d73ba1bb016c9325d0a7fdb84519d3443622;hp=d776b14ebe9d4d05795d8e15ae1b882598c8ae54;hpb=14bf87881b6e6788447e46108b5bb074d8c5f726;p=thirdparty%2Fsystemd.git diff --git a/man/sd_journal_add_match.xml b/man/sd_journal_add_match.xml index d776b14ebe9..83f7fe9242d 100644 --- a/man/sd_journal_add_match.xml +++ b/man/sd_journal_add_match.xml @@ -1,220 +1,177 @@ - - - - - - - - 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_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. 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 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. - - - - Notes - - The sd_journal_add_match(), - sd_journal_add_disjunction(), - sd_journal_add_conjunction() and - sd_journal_flush_matches() - interfaces are available as a shared library, which can - be compiled and linked to with the - libsystemd 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): - - ... + + + + + + + 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); + 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); } - - - - - See Also - - - systemd1, - sd-journal3, - sd_journal_open3, - sd_journal_next3, - sd_journal_get_data3, - systemd.journal-fields7 - - + + + + See Also + + + systemd1, + sd-journal3, + sd_journal_open3, + sd_journal_next3, + sd_journal_get_data3, + systemd.journal-fields7 + +