sd_journal_query_unique

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

To enumerate all field names currently in use (and thus all suitable field parameters for `sd_journal_query_unique()`), use the sd_journal_enumerate_fields 3 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

## 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:

## See Also

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