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_query_unique.xml | 184 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 184 insertions(+) create mode 100644 man/sd_journal_query_unique.xml (limited to 'man/sd_journal_query_unique.xml') diff --git a/man/sd_journal_query_unique.xml b/man/sd_journal_query_unique.xml new file mode 100644 index 0000000..005c8d5 --- /dev/null +++ b/man/sd_journal_query_unique.xml @@ -0,0 +1,184 @@ + + + + + + + + sd_journal_query_unique + systemd + + + + sd_journal_query_unique + 3 + + + + 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 + + + + + #include <systemd/sd-journal.h> + + + int sd_journal_query_unique + sd_journal *j + 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 + const void **data + size_t *length + + + + void sd_journal_restart_unique + sd_journal *j + + + + SD_JOURNAL_FOREACH_UNIQUE + sd_journal *j + const void *data + size_t length + + + + + + + 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, + 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 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 + invocation of sd_journal_enumerate_unique() + 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_available_unique(). + + Note that these functions currently are not influenced by + matches set with sd_journal_add_match() but + this might change in a later version of this software. + + To enumerate all field names currently in use (and thus all suitable field parameters for + sd_journal_query_unique()), use the + sd_journal_enumerate_fields3 + call. + + + + Return Value + + sd_journal_query_unique() returns 0 on success or a negative errno-style error + code. sd_journal_enumerate_unique() 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: + + + + + + + + + + + + + + + + + Notes + + + + + + + + Examples + + 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: + + + + + + History + sd_journal_query_unique(), + sd_journal_enumerate_unique(), + sd_journal_restart_unique(), and + SD_JOURNAL_FOREACH_UNIQUE() were added in version 195. + sd_journal_enumerate_available_unique() was added in version 246. + + + + See Also + + + systemd1, + systemd.journal-fields7, + sd-journal3, + sd_journal_open3, + sd_journal_enumerate_fields3, + sd_journal_get_data3, + sd_journal_add_match3 + + + + -- cgit v1.2.3