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-fields 7. 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.

## 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-config 1 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

systemd 1, systemd.journal-fields 7, sd-journal 3, sd_journal_open 3, sd_journal_get_data 3, sd_journal_add_match 3