sd_journal_query_unique

Index

## Name

sd_journal_query_unique, sd_journal_enumerate_unique, sd_journal_restart_unique, SD_JOURNAL_FOREACH_UNIQUE — Read unique data fields from the journal

## Synopsis

    #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 '='.

`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)