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 <contrib>Developer
</contrib>
18 <firstname>Lennart
</firstname>
19 <surname>Poettering
</surname>
20 <email>lennart@poettering.net
</email>
26 <refentrytitle>sd_journal_query_unique
</refentrytitle>
27 <manvolnum>3</manvolnum>
31 <refname>sd_journal_query_unique
</refname>
32 <refname>sd_journal_enumerate_unique
</refname>
33 <refname>sd_journal_restart_unique
</refname>
34 <refname>SD_JOURNAL_FOREACH_UNIQUE
</refname>
35 <refpurpose>Read unique data fields from the journal
</refpurpose>
40 <funcsynopsisinfo>#include
<systemd/sd-journal.h
></funcsynopsisinfo>
43 <funcdef>int
<function>sd_journal_query_unique
</function></funcdef>
44 <paramdef>sd_journal *
<parameter>j
</parameter></paramdef>
45 <paramdef>const char *
<parameter>field
</parameter></paramdef>
49 <funcdef>int
<function>sd_journal_enumerate_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>
56 <funcdef>void
<function>sd_journal_restart_unique
</function></funcdef>
57 <paramdef>sd_journal *
<parameter>j
</parameter></paramdef>
61 <funcdef><function>SD_JOURNAL_FOREACH_UNIQUE
</function></funcdef>
62 <paramdef>sd_journal *
<parameter>j
</parameter></paramdef>
63 <paramdef>const void *
<parameter>data
</parameter></paramdef>
64 <paramdef>size_t
<parameter>length
</parameter></paramdef>
71 <title>Description
</title>
73 <para><function>sd_journal_query_unique()
</function> queries the
74 journal for all unique values the specified field can take. It
75 takes two arguments: the journal to query and the field name to
76 look for. Well-known field names are listed on
77 <citerefentry><refentrytitle>systemd.journal-fields
</refentrytitle><manvolnum>7</manvolnum></citerefentry>.
78 Field names must be specified without a trailing '='. After this
79 function has been executed successfully the field values may be
80 queried using
<function>sd_journal_enumerate_unique()
</function>.
81 Invoking this call a second time will change the field name being
82 queried and reset the enumeration index to the first field value
85 <para><function>sd_journal_enumerate_unique()
</function> may be
86 used to iterate through all data fields which match the previously
87 selected field name as set with
88 <function>sd_journal_query_unique()
</function>. On each invocation
89 the next field data matching the field name is returned. The order
90 of the returned data fields is not defined. It takes three
91 arguments: the journal context object, plus a pair of pointers to
92 pointer/size variables where the data object and its size shall be
93 stored in. The returned data is in a read-only memory map and is
94 only valid until the next invocation of
95 <function>sd_journal_enumerate_unique()
</function>. Note that the
96 data returned will be prefixed with the field name and '='. Note
97 that this call is subject to the data field size threshold as
99 <function>sd_journal_set_data_threshold()
</function>.
</para>
101 <para><function>sd_journal_restart_unique()
</function> resets the
102 data enumeration index to the beginning of the list. The next
103 invocation of
<function>sd_journal_enumerate_unique()
</function>
104 will return the first field data matching the field name
108 <function>SD_JOURNAL_FOREACH_UNIQUE()
</function> macro may be used
109 as a handy wrapper around
110 <function>sd_journal_restart_unique()
</function> and
111 <function>sd_journal_enumerate_unique()
</function>.
</para>
113 <para>Note that these functions currently are not influenced by
114 matches set with
<function>sd_journal_add_match()
</function> but
115 this might change in a later version of this software.
</para>
117 <para>To enumerate all field names currently in use (and thus all suitable field parameters for
118 <function>sd_journal_query_unique()
</function>), use the
119 <citerefentry><refentrytitle>sd_journal_enumerate_fields
</refentrytitle><manvolnum>3</manvolnum></citerefentry>
124 <title>Return Value
</title>
126 <para><function>sd_journal_query_unique()
</function> returns
0 on
127 success or a negative errno-style error code.
128 <function>sd_journal_enumerate_unique()
</function> returns a
129 positive integer if the next field data has been read,
0 when no
130 more fields are known, or a negative errno-style error code.
131 <function>sd_journal_restart_unique()
</function> returns
138 <para>All functions listed here are thread-agnostic and only a single thread may operate
139 on a given
<structname>sd_journal
</structname> object.
</para>
141 <xi:include href=
"libsystemd-pkgconfig.xml" xpointer=
"pkgconfig-text"/>
145 <title>Examples
</title>
147 <para>Use the
<function>SD_JOURNAL_FOREACH_UNIQUE
</function> macro
148 to iterate through all values a field of the journal can take. The
149 following example lists all unit names referenced in the
152 <programlisting>#include
<stdio.h
>
153 #include
<string.h
>
154 #include
<systemd/sd-journal.h
>
156 int main(int argc, char *argv[]) {
162 r = sd_journal_open(
&j, SD_JOURNAL_LOCAL_ONLY);
164 fprintf(stderr,
"Failed to open journal: %s\n", strerror(-r));
167 r = sd_journal_query_unique(j,
"_SYSTEMD_UNIT");
169 fprintf(stderr,
"Failed to query journal: %s\n", strerror(-r));
172 SD_JOURNAL_FOREACH_UNIQUE(j, d, l)
173 printf(
"%.*s\n", (int) l, (const char*) d);
181 <title>See Also
</title>
184 <citerefentry><refentrytitle>systemd
</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
185 <citerefentry><refentrytitle>systemd.journal-fields
</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
186 <citerefentry><refentrytitle>sd-journal
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
187 <citerefentry><refentrytitle>sd_journal_open
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
188 <citerefentry><refentrytitle>sd_journal_enumerate_fields
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
189 <citerefentry><refentrytitle>sd_journal_get_data
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
190 <citerefentry><refentrytitle>sd_journal_add_match
</refentrytitle><manvolnum>3</manvolnum></citerefentry>