1 <?xml version='
1.0'
?> <!--*-nxml-*-->
2 <!DOCTYPE refentry PUBLIC
"-//OASIS//DTD DocBook XML V4.2//EN"
3 "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
6 SPDX-License-Identifier: LGPL-2.1+
9 <refentry id=
"sd_journal_query_unique" xmlns:
xi=
"http://www.w3.org/2001/XInclude">
12 <title>sd_journal_query_unique
</title>
13 <productname>systemd
</productname>
17 <refentrytitle>sd_journal_query_unique
</refentrytitle>
18 <manvolnum>3</manvolnum>
22 <refname>sd_journal_query_unique
</refname>
23 <refname>sd_journal_enumerate_unique
</refname>
24 <refname>sd_journal_restart_unique
</refname>
25 <refname>SD_JOURNAL_FOREACH_UNIQUE
</refname>
26 <refpurpose>Read unique data fields from the journal
</refpurpose>
31 <funcsynopsisinfo>#include
<systemd/sd-journal.h
></funcsynopsisinfo>
34 <funcdef>int
<function>sd_journal_query_unique
</function></funcdef>
35 <paramdef>sd_journal *
<parameter>j
</parameter></paramdef>
36 <paramdef>const char *
<parameter>field
</parameter></paramdef>
40 <funcdef>int
<function>sd_journal_enumerate_unique
</function></funcdef>
41 <paramdef>sd_journal *
<parameter>j
</parameter></paramdef>
42 <paramdef>const void **
<parameter>data
</parameter></paramdef>
43 <paramdef>size_t *
<parameter>length
</parameter></paramdef>
47 <funcdef>void
<function>sd_journal_restart_unique
</function></funcdef>
48 <paramdef>sd_journal *
<parameter>j
</parameter></paramdef>
52 <funcdef><function>SD_JOURNAL_FOREACH_UNIQUE
</function></funcdef>
53 <paramdef>sd_journal *
<parameter>j
</parameter></paramdef>
54 <paramdef>const void *
<parameter>data
</parameter></paramdef>
55 <paramdef>size_t
<parameter>length
</parameter></paramdef>
62 <title>Description
</title>
64 <para><function>sd_journal_query_unique()
</function> queries the
65 journal for all unique values the specified field can take. It
66 takes two arguments: the journal to query and the field name to
67 look for. Well-known field names are listed on
68 <citerefentry><refentrytitle>systemd.journal-fields
</refentrytitle><manvolnum>7</manvolnum></citerefentry>.
69 Field names must be specified without a trailing '='. After this
70 function has been executed successfully the field values may be
71 queried using
<function>sd_journal_enumerate_unique()
</function>.
72 Invoking this call a second time will change the field name being
73 queried and reset the enumeration index to the first field value
76 <para><function>sd_journal_enumerate_unique()
</function> may be
77 used to iterate through all data fields which match the previously
78 selected field name as set with
79 <function>sd_journal_query_unique()
</function>. On each invocation
80 the next field data matching the field name is returned. The order
81 of the returned data fields is not defined. It takes three
82 arguments: the journal context object, plus a pair of pointers to
83 pointer/size variables where the data object and its size shall be
84 stored in. The returned data is in a read-only memory map and is
85 only valid until the next invocation of
86 <function>sd_journal_enumerate_unique()
</function>. Note that the
87 data returned will be prefixed with the field name and '='. Note
88 that this call is subject to the data field size threshold as
90 <function>sd_journal_set_data_threshold()
</function>.
</para>
92 <para><function>sd_journal_restart_unique()
</function> resets the
93 data enumeration index to the beginning of the list. The next
94 invocation of
<function>sd_journal_enumerate_unique()
</function>
95 will return the first field data matching the field name
99 <function>SD_JOURNAL_FOREACH_UNIQUE()
</function> macro may be used
100 as a handy wrapper around
101 <function>sd_journal_restart_unique()
</function> and
102 <function>sd_journal_enumerate_unique()
</function>.
</para>
104 <para>Note that these functions currently are not influenced by
105 matches set with
<function>sd_journal_add_match()
</function> but
106 this might change in a later version of this software.
</para>
108 <para>To enumerate all field names currently in use (and thus all suitable field parameters for
109 <function>sd_journal_query_unique()
</function>), use the
110 <citerefentry><refentrytitle>sd_journal_enumerate_fields
</refentrytitle><manvolnum>3</manvolnum></citerefentry>
115 <title>Return Value
</title>
117 <para><function>sd_journal_query_unique()
</function> returns
0 on
118 success or a negative errno-style error code.
119 <function>sd_journal_enumerate_unique()
</function> returns a
120 positive integer if the next field data has been read,
0 when no
121 more fields are known, or a negative errno-style error code.
122 <function>sd_journal_restart_unique()
</function> returns
129 <xi:include href=
"threads-aware.xml" xpointer=
"strict"/>
131 <xi:include href=
"libsystemd-pkgconfig.xml" xpointer=
"pkgconfig-text"/>
135 <title>Examples
</title>
137 <para>Use the
<function>SD_JOURNAL_FOREACH_UNIQUE
</function> macro
138 to iterate through all values a field of the journal can take. The
139 following example lists all unit names referenced in the
142 <programlisting><xi:include href=
"journal-iterate-unique.c" parse=
"text" /></programlisting>
146 <title>See Also
</title>
149 <citerefentry><refentrytitle>systemd
</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
150 <citerefentry><refentrytitle>systemd.journal-fields
</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
151 <citerefentry><refentrytitle>sd-journal
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
152 <citerefentry><refentrytitle>sd_journal_open
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
153 <citerefentry><refentrytitle>sd_journal_enumerate_fields
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
154 <citerefentry><refentrytitle>sd_journal_get_data
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
155 <citerefentry><refentrytitle>sd_journal_add_match
</refentrytitle><manvolnum>3</manvolnum></citerefentry>