From 9fdd60e58532607eeda4e396bebea2c22143cac8 Mon Sep 17 00:00:00 2001 From: Luke Shumaker Date: Wed, 10 May 2017 14:47:43 -0400 Subject: ./tools/notsd-move --- src/libsystemd/sd_journal_query_unique.xml | 215 +++++++++++++++++++++++++++++ 1 file changed, 215 insertions(+) create mode 100644 src/libsystemd/sd_journal_query_unique.xml (limited to 'src/libsystemd/sd_journal_query_unique.xml') diff --git a/src/libsystemd/sd_journal_query_unique.xml b/src/libsystemd/sd_journal_query_unique.xml new file mode 100644 index 0000000000..d7a41a039c --- /dev/null +++ b/src/libsystemd/sd_journal_query_unique.xml @@ -0,0 +1,215 @@ + + + + + + + + + sd_journal_query_unique + systemd + + + + Developer + Lennart + Poettering + lennart@poettering.net + + + + + + sd_journal_query_unique + 3 + + + + sd_journal_query_unique + sd_journal_enumerate_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_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. + 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_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_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_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() 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. + + + + Notes + + All functions listed here are thread-agnostic and only a single thread may operate + on a given sd_journal object. + + The sd_journal_query_unique(), + sd_journal_enumerate_unique() and + sd_journal_restart_unique() interfaces are + available as a shared library, which can be compiled and linked to + with the + libsystemd pkg-config1 + file. + + + + 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: + + #include <stdio.h> +#include <string.h> +#include <systemd/sd-journal.h> + +int main(int argc, char *argv[]) { + sd_journal *j; + const void *d; + size_t l; + int r; + + r = sd_journal_open(&j, SD_JOURNAL_LOCAL_ONLY); + if (r < 0) { + fprintf(stderr, "Failed to open journal: %s\n", strerror(-r)); + return 1; + } + r = sd_journal_query_unique(j, "_SYSTEMD_UNIT"); + if (r < 0) { + fprintf(stderr, "Failed to query journal: %s\n", strerror(-r)); + return 1; + } + SD_JOURNAL_FOREACH_UNIQUE(j, d, l) + printf("%.*s\n", (int) l, (const char*) d); + sd_journal_close(j); + return 0; +} + + + + + 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-54-g00ecf