1 <?xml version='
1.0'
?> <!--*-nxml-*-->
2 <!DOCTYPE refentry PUBLIC
"-//OASIS//DTD DocBook XML V4.5//EN"
3 "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
4 <!-- SPDX-License-Identifier: LGPL-2.1+ -->
6 <refentry id=
"sd_journal_query_unique" xmlns:
xi=
"http://www.w3.org/2001/XInclude">
9 <title>sd_journal_query_unique
</title>
10 <productname>systemd
</productname>
14 <refentrytitle>sd_journal_query_unique
</refentrytitle>
15 <manvolnum>3</manvolnum>
19 <refname>sd_journal_query_unique
</refname>
20 <refname>sd_journal_enumerate_unique
</refname>
21 <refname>sd_journal_restart_unique
</refname>
22 <refname>SD_JOURNAL_FOREACH_UNIQUE
</refname>
23 <refpurpose>Read unique data fields from the journal
</refpurpose>
28 <funcsynopsisinfo>#include
<systemd/sd-journal.h
></funcsynopsisinfo>
31 <funcdef>int
<function>sd_journal_query_unique
</function></funcdef>
32 <paramdef>sd_journal *
<parameter>j
</parameter></paramdef>
33 <paramdef>const char *
<parameter>field
</parameter></paramdef>
37 <funcdef>int
<function>sd_journal_enumerate_unique
</function></funcdef>
38 <paramdef>sd_journal *
<parameter>j
</parameter></paramdef>
39 <paramdef>const void **
<parameter>data
</parameter></paramdef>
40 <paramdef>size_t *
<parameter>length
</parameter></paramdef>
44 <funcdef>void
<function>sd_journal_restart_unique
</function></funcdef>
45 <paramdef>sd_journal *
<parameter>j
</parameter></paramdef>
49 <funcdef><function>SD_JOURNAL_FOREACH_UNIQUE
</function></funcdef>
50 <paramdef>sd_journal *
<parameter>j
</parameter></paramdef>
51 <paramdef>const void *
<parameter>data
</parameter></paramdef>
52 <paramdef>size_t
<parameter>length
</parameter></paramdef>
59 <title>Description
</title>
61 <para><function>sd_journal_query_unique()
</function> queries the
62 journal for all unique values the specified field can take. It
63 takes two arguments: the journal to query and the field name to
64 look for. Well-known field names are listed on
65 <citerefentry><refentrytitle>systemd.journal-fields
</refentrytitle><manvolnum>7</manvolnum></citerefentry>.
66 Field names must be specified without a trailing '='. After this
67 function has been executed successfully the field values may be
68 queried using
<function>sd_journal_enumerate_unique()
</function>.
69 Invoking this call a second time will change the field name being
70 queried and reset the enumeration index to the first field value
73 <para><function>sd_journal_enumerate_unique()
</function> may be
74 used to iterate through all data fields which match the previously
75 selected field name as set with
76 <function>sd_journal_query_unique()
</function>. On each invocation
77 the next field data matching the field name is returned. The order
78 of the returned data fields is not defined. It takes three
79 arguments: the journal context object, plus a pair of pointers to
80 pointer/size variables where the data object and its size shall be
81 stored in. The returned data is in a read-only memory map and is
82 only valid until the next invocation of
83 <function>sd_journal_enumerate_unique()
</function>. Note that the
84 data returned will be prefixed with the field name and '='. Note
85 that this call is subject to the data field size threshold as
87 <function>sd_journal_set_data_threshold()
</function>.
</para>
89 <para><function>sd_journal_restart_unique()
</function> resets the
90 data enumeration index to the beginning of the list. The next
91 invocation of
<function>sd_journal_enumerate_unique()
</function>
92 will return the first field data matching the field name
96 <function>SD_JOURNAL_FOREACH_UNIQUE()
</function> macro may be used
97 as a handy wrapper around
98 <function>sd_journal_restart_unique()
</function> and
99 <function>sd_journal_enumerate_unique()
</function>.
</para>
101 <para>Note that these functions currently are not influenced by
102 matches set with
<function>sd_journal_add_match()
</function> but
103 this might change in a later version of this software.
</para>
105 <para>To enumerate all field names currently in use (and thus all suitable field parameters for
106 <function>sd_journal_query_unique()
</function>), use the
107 <citerefentry><refentrytitle>sd_journal_enumerate_fields
</refentrytitle><manvolnum>3</manvolnum></citerefentry>
112 <title>Return Value
</title>
114 <para><function>sd_journal_query_unique()
</function> returns
0 on
115 success or a negative errno-style error code.
116 <function>sd_journal_enumerate_unique()
</function> returns a
117 positive integer if the next field data has been read,
0 when no
118 more fields are known, or a negative errno-style error code.
119 <function>sd_journal_restart_unique()
</function> returns
126 <xi:include href=
"threads-aware.xml" xpointer=
"strict"/>
128 <xi:include href=
"libsystemd-pkgconfig.xml" xpointer=
"pkgconfig-text"/>
132 <title>Examples
</title>
134 <para>Use the
<function>SD_JOURNAL_FOREACH_UNIQUE
</function> macro
135 to iterate through all values a field of the journal can take. The
136 following example lists all unit names referenced in the
139 <programlisting><xi:include href=
"journal-iterate-unique.c" parse=
"text" /></programlisting>
143 <title>See Also
</title>
146 <citerefentry><refentrytitle>systemd
</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
147 <citerefentry><refentrytitle>systemd.journal-fields
</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
148 <citerefentry><refentrytitle>sd-journal
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
149 <citerefentry><refentrytitle>sd_journal_open
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
150 <citerefentry><refentrytitle>sd_journal_enumerate_fields
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
151 <citerefentry><refentrytitle>sd_journal_get_data
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
152 <citerefentry><refentrytitle>sd_journal_add_match
</refentrytitle><manvolnum>3</manvolnum></citerefentry>