From: Lennart Poettering Date: Thu, 18 Oct 2012 16:48:45 +0000 (+0200) Subject: man: add missing man page X-Git-Tag: v195~66 X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?p=elogind.git;a=commitdiff_plain;h=1a2be33aa584df0d2fe8fa30d35b7c04eb092920 man: add missing man page --- diff --git a/man/sd_journal_query_unique.xml b/man/sd_journal_query_unique.xml new file mode 100644 index 000000000..278506ae1 --- /dev/null +++ b/man/sd_journal_query_unique.xml @@ -0,0 +1,214 @@ + + + + + + + + + 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 '='. + + 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. + + + + 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 + + The sd_journal_query_unique(), + sd_journal_enumerate_unique() and + sd_journal_restart_unique() + interfaces are available as shared library, which can + be compiled and linked to with the + libsystemd-journal + 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 char *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, d); + sd_journal_close(j); + return 0; +} + + + + + See Also + + + systemd1, + systemd.journal-fields7, + sd-journal3, + sd_journal_open3, + sd_journal_get_data3, + sd_journal_add_match3 + + + +