From 0da322d9a4a78dedadf514f04657c0b2615d1811 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Zbigniew=20J=C4=99drzejewski-Szmek?= Date: Tue, 21 Jul 2020 17:16:52 +0200 Subject: [PATCH] man: update docs with the new functions and other enhancements --- man/sd_journal_get_data.xml | 143 ++++++++++++++++++++++++-------- man/sd_journal_query_unique.xml | 103 +++++++++++++---------- 2 files changed, 170 insertions(+), 76 deletions(-) diff --git a/man/sd_journal_get_data.xml b/man/sd_journal_get_data.xml index 0a0030e300..209f5deaa1 100644 --- a/man/sd_journal_get_data.xml +++ b/man/sd_journal_get_data.xml @@ -18,6 +18,7 @@ sd_journal_get_data sd_journal_enumerate_data + sd_journal_enumerate_available_data sd_journal_restart_data SD_JOURNAL_FOREACH_DATA sd_journal_set_data_threshold @@ -44,6 +45,13 @@ size_t *length + + int sd_journal_enumerate_available_data + sd_journal *j + const void **data + size_t *length + + void sd_journal_restart_data sd_journal *j @@ -73,24 +81,18 @@ Description - sd_journal_get_data() gets the data - object associated with a specific field from the current journal - entry. It takes four arguments: the journal context object, a - string with the field name to request, plus a pair of pointers to - pointer/size variables where the data object and its size shall be - stored in. The field name should be an entry field name. - Well-known field names are listed in - systemd.journal-fields7. - The returned data is in a read-only memory map and is only valid - until the next invocation of - sd_journal_get_data() or - sd_journal_enumerate_data(), or the read - pointer is altered. Note that the data returned will be prefixed - with the field name and '='. Also note that, by default, data fields - larger than 64K might get truncated to 64K. This threshold may be - changed and turned off with - sd_journal_set_data_threshold() (see - below). + sd_journal_get_data() gets the data object associated with a specific field + from the current journal entry. It takes four arguments: the journal context object, a string with the + field name to request, plus a pair of pointers to pointer/size variables where the data object and its + size shall be stored in. The field name should be an entry field name. Well-known field names are listed in + systemd.journal-fields7, + but any field can be specified. The returned data is in a read-only memory map and is only valid until + the next invocation of sd_journal_get_data(), + sd_journal_enumerate_data(), + sd_journal_enumerate_available_data(), or when the read pointer is altered. Note + that the data returned will be prefixed with the field name and =. Also note that, by + default, data fields larger than 64K might get truncated to 64K. This threshold may be changed and turned + off with sd_journal_set_data_threshold() (see below). sd_journal_enumerate_data() may be used to iterate through all fields of the current entry. On each @@ -99,15 +101,18 @@ format as with sd_journal_get_data() and also follows the same life-time semantics. + sd_journal_enumerate_available_data() is similar to + sd_journal_enumerate_data(), but silently skips any fields which may be valid, but + are too large or not supported by current implementation. + sd_journal_restart_data() resets the data enumeration index to the beginning of the entry. The next invocation of sd_journal_enumerate_data() will return the first field of the entry again. - Note that the SD_JOURNAL_FOREACH_DATA() - macro may be used as a handy wrapper around - sd_journal_restart_data() and - sd_journal_enumerate_data(). + Note that the SD_JOURNAL_FOREACH_DATA() macro may be used as a handy wrapper + around sd_journal_restart_data() and + sd_journal_enumerate_available_data(). Note that these functions will not work before sd_journal_next3 @@ -139,18 +144,88 @@ Return Value - sd_journal_get_data() returns 0 on - success or a negative errno-style error code. If the current entry - does not include the specified field, -ENOENT is returned. If - sd_journal_next3 - has not been called at least once, -EADDRNOTAVAIL is returned. - sd_journal_enumerate_data() returns a - positive integer if the next field has been read, 0 when no more - fields are known, or a negative errno-style error code. - sd_journal_restart_data() returns nothing. - sd_journal_set_data_threshold() and - sd_journal_get_threshold() return 0 on - success or a negative errno-style error code. + sd_journal_get_data() returns 0 on success or a negative errno-style error + code. sd_journal_enumerate_data() and + sd_journal_enumerate_available_data() return a positive integer if the next field + has been read, 0 when no more fields remain, or a negative errno-style error code. + sd_journal_restart_data() doesn't return anything. + sd_journal_set_data_threshold() and sd_journal_get_threshold() + return 0 on success or a negative errno-style error code. + + + Errors + + Returned errors may indicate the following problems: + + + + -EINVAL + + One of the required parameters is NULL or invalid. + + + + + -ECHILD + + The journal object was created in a different process. + + + + -EADDRNOTAVAIL + + The read pointer is not positioned at a valid entry; + sd_journal_next3 + or a related call has not been called at least once. + + + + -ENOENT + + The current entry does not include the specified field. + + + + + -ENOMEM + + Memory allocation failed. + + + + -ENOBUFS + + A compressed entry is too large. + + + + -E2BIG + + The data field is too large for this computer architecture (e.g. above 4 GB on a + 32-bit architecture). + + + + -EPROTONOSUPPORT + + The journal is compressed with an unsupported method or the journal uses an + unsupported feature. + + + + -EBADMSG + + The journal is corrupted (possibly just the entry being iterated over). + + + + + -EIO + + An I/O error was reported by the kernel. + + + diff --git a/man/sd_journal_query_unique.xml b/man/sd_journal_query_unique.xml index 1bf83968dd..88beaa6460 100644 --- a/man/sd_journal_query_unique.xml +++ b/man/sd_journal_query_unique.xml @@ -18,6 +18,7 @@ sd_journal_query_unique sd_journal_enumerate_unique + sd_journal_enumerate_available_unique sd_journal_restart_unique SD_JOURNAL_FOREACH_UNIQUE Read unique data fields from the journal @@ -33,6 +34,13 @@ const char *field + + int sd_journal_enumerate_available_unique + sd_journal *j + const void **data + size_t *length + + int sd_journal_enumerate_unique sd_journal *j @@ -58,33 +66,31 @@ Description - sd_journal_query_unique() queries the - journal for all unique values the specified field can take. It - takes two arguments: the journal to query and the field name to - look for. Well-known field names are listed on - systemd.journal-fields7. - Field names must be specified without a trailing '='. After this - function has been executed successfully the field values may be - queried using sd_journal_enumerate_unique(). - Invoking this call a second time will change the field name being - queried and reset the enumeration index to the first field value - that matches. + sd_journal_query_unique() queries the journal for all unique values the + specified field can take. It takes two arguments: the journal to query and the field name to look + for. Well-known field names are listed on + systemd.journal-fields7, + but any field can be specified. Field names must be specified without a trailing + =. After this function has been executed successfully the field values may be queried + using sd_journal_enumerate_unique() and + sd_journal_enumerate_available_unique(). Invoking one of those calls will change the + field name being queried and reset the enumeration index to the first field value that matches. - sd_journal_enumerate_unique() may be - used to iterate through all data fields which match the previously - selected field name as set with - sd_journal_query_unique(). On each invocation - the next field data matching the field name is returned. The order - of the returned data fields is not defined. It takes three - arguments: the journal context object, plus a pair of pointers to - pointer/size variables where the data object and its size shall be - stored in. The returned data is in a read-only memory map and is - only valid until the next invocation of - sd_journal_enumerate_unique(). Note that the - data returned will be prefixed with the field name and '='. Note - that this call is subject to the data field size threshold as - controlled by - sd_journal_set_data_threshold(). + sd_journal_enumerate_unique() may be used to iterate through all data fields + which match the previously selected field name as set with + sd_journal_query_unique(). On each invocation the next field data matching the field + name is returned. The order of the returned data fields is not defined. It takes three arguments: the + journal object, plus a pair of pointers to pointer/size variables where the data object and its size + shall be stored. The returned data is in a read-only memory map and is only valid until the next + invocation of sd_journal_enumerate_unique(). Note that the data returned will be + prefixed with the field name and =. Note that this call is subject to the data field + size threshold as controlled by sd_journal_set_data_threshold() and only the initial + part of the field up to the threshold is returned. An error is returned for fields which cannot be + retrieved. See the error list below for details. + + sd_journal_enumerate_available_unique() is similar to + sd_journal_enumerate_unique(), but silently skips any fields which may be valid, but + are too large or not supported by current implementation. sd_journal_restart_unique() resets the data enumeration index to the beginning of the list. The next @@ -92,11 +98,9 @@ will return the first field data matching the field name again. - Note that the - SD_JOURNAL_FOREACH_UNIQUE() macro may be used - as a handy wrapper around - sd_journal_restart_unique() and - sd_journal_enumerate_unique(). + Note that the SD_JOURNAL_FOREACH_UNIQUE() macro may be used as a handy wrapper + around sd_journal_restart_unique() and + sd_journal_enumerate_available_unique(). Note that these functions currently are not influenced by matches set with sd_journal_add_match() but @@ -111,13 +115,29 @@ Return Value - sd_journal_query_unique() returns 0 on - success or a negative errno-style error code. - sd_journal_enumerate_unique() returns a - positive integer if the next field data has been read, 0 when no - more fields are known, or a negative errno-style error code. - sd_journal_restart_unique() returns - nothing. + sd_journal_query_unique() returns 0 on success or a negative errno-style error + code. sd_journal_enumerate_unique() and and + sd_journal_query_available_unique() return a positive integer if the next field data + has been read, 0 when no more fields remain, or a negative errno-style error code. + sd_journal_restart_unique() doesn't return anything. + + + Errors + + Returned errors may indicate the following problems: + + + + + + + + + + + + + @@ -131,10 +151,9 @@ Examples - Use the SD_JOURNAL_FOREACH_UNIQUE macro - to iterate through all values a field of the journal can take. The - following example lists all unit names referenced in the - journal: + Use the SD_JOURNAL_FOREACH_UNIQUE macro to iterate through all values a field + of the journal can take (and which can be accessed on the given architecture and are not compressed with + an unsupported mechanism). The following example lists all unit names referenced in the journal: