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+
8 This file is part of systemd.
10 Copyright 2012 Lennart Poettering
13 <refentry id=
"sd_journal_query_unique">
16 <title>sd_journal_query_unique
</title>
17 <productname>systemd
</productname>
21 <contrib>Developer
</contrib>
22 <firstname>Lennart
</firstname>
23 <surname>Poettering
</surname>
24 <email>lennart@poettering.net
</email>
30 <refentrytitle>sd_journal_query_unique
</refentrytitle>
31 <manvolnum>3</manvolnum>
35 <refname>sd_journal_query_unique
</refname>
36 <refname>sd_journal_enumerate_unique
</refname>
37 <refname>sd_journal_restart_unique
</refname>
38 <refname>SD_JOURNAL_FOREACH_UNIQUE
</refname>
39 <refpurpose>Read unique data fields from the journal
</refpurpose>
44 <funcsynopsisinfo>#include
<systemd/sd-journal.h
></funcsynopsisinfo>
47 <funcdef>int
<function>sd_journal_query_unique
</function></funcdef>
48 <paramdef>sd_journal *
<parameter>j
</parameter></paramdef>
49 <paramdef>const char *
<parameter>field
</parameter></paramdef>
53 <funcdef>int
<function>sd_journal_enumerate_unique
</function></funcdef>
54 <paramdef>sd_journal *
<parameter>j
</parameter></paramdef>
55 <paramdef>const void **
<parameter>data
</parameter></paramdef>
56 <paramdef>size_t *
<parameter>length
</parameter></paramdef>
60 <funcdef>void
<function>sd_journal_restart_unique
</function></funcdef>
61 <paramdef>sd_journal *
<parameter>j
</parameter></paramdef>
65 <funcdef><function>SD_JOURNAL_FOREACH_UNIQUE
</function></funcdef>
66 <paramdef>sd_journal *
<parameter>j
</parameter></paramdef>
67 <paramdef>const void *
<parameter>data
</parameter></paramdef>
68 <paramdef>size_t
<parameter>length
</parameter></paramdef>
75 <title>Description
</title>
77 <para><function>sd_journal_query_unique()
</function> queries the
78 journal for all unique values the specified field can take. It
79 takes two arguments: the journal to query and the field name to
80 look for. Well-known field names are listed on
81 <citerefentry><refentrytitle>systemd.journal-fields
</refentrytitle><manvolnum>7</manvolnum></citerefentry>.
82 Field names must be specified without a trailing '='. After this
83 function has been executed successfully the field values may be
84 queried using
<function>sd_journal_enumerate_unique()
</function>.
85 Invoking this call a second time will change the field name being
86 queried and reset the enumeration index to the first field value
89 <para><function>sd_journal_enumerate_unique()
</function> may be
90 used to iterate through all data fields which match the previously
91 selected field name as set with
92 <function>sd_journal_query_unique()
</function>. On each invocation
93 the next field data matching the field name is returned. The order
94 of the returned data fields is not defined. It takes three
95 arguments: the journal context object, plus a pair of pointers to
96 pointer/size variables where the data object and its size shall be
97 stored in. The returned data is in a read-only memory map and is
98 only valid until the next invocation of
99 <function>sd_journal_enumerate_unique()
</function>. Note that the
100 data returned will be prefixed with the field name and '='. Note
101 that this call is subject to the data field size threshold as
103 <function>sd_journal_set_data_threshold()
</function>.
</para>
105 <para><function>sd_journal_restart_unique()
</function> resets the
106 data enumeration index to the beginning of the list. The next
107 invocation of
<function>sd_journal_enumerate_unique()
</function>
108 will return the first field data matching the field name
112 <function>SD_JOURNAL_FOREACH_UNIQUE()
</function> macro may be used
113 as a handy wrapper around
114 <function>sd_journal_restart_unique()
</function> and
115 <function>sd_journal_enumerate_unique()
</function>.
</para>
117 <para>Note that these functions currently are not influenced by
118 matches set with
<function>sd_journal_add_match()
</function> but
119 this might change in a later version of this software.
</para>
121 <para>To enumerate all field names currently in use (and thus all suitable field parameters for
122 <function>sd_journal_query_unique()
</function>), use the
123 <citerefentry><refentrytitle>sd_journal_enumerate_fields
</refentrytitle><manvolnum>3</manvolnum></citerefentry>
128 <title>Return Value
</title>
130 <para><function>sd_journal_query_unique()
</function> returns
0 on
131 success or a negative errno-style error code.
132 <function>sd_journal_enumerate_unique()
</function> returns a
133 positive integer if the next field data has been read,
0 when no
134 more fields are known, or a negative errno-style error code.
135 <function>sd_journal_restart_unique()
</function> returns
142 <para>All functions listed here are thread-agnostic and only a single thread may operate
143 on a given
<structname>sd_journal
</structname> object.
</para>
145 <para>The
<function>sd_journal_query_unique()
</function>,
146 <function>sd_journal_enumerate_unique()
</function> and
147 <function>sd_journal_restart_unique()
</function> interfaces are
148 available as a shared library, which can be compiled and linked to
150 <constant>libsystemd
</constant> <citerefentry project='die-net'
><refentrytitle>pkg-config
</refentrytitle><manvolnum>1</manvolnum></citerefentry>
155 <title>Examples
</title>
157 <para>Use the
<function>SD_JOURNAL_FOREACH_UNIQUE
</function> macro
158 to iterate through all values a field of the journal can take. The
159 following example lists all unit names referenced in the
162 <programlisting>#include
<stdio.h
>
163 #include
<string.h
>
164 #include
<systemd/sd-journal.h
>
166 int main(int argc, char *argv[]) {
172 r = sd_journal_open(
&j, SD_JOURNAL_LOCAL_ONLY);
174 fprintf(stderr,
"Failed to open journal: %s\n", strerror(-r));
177 r = sd_journal_query_unique(j,
"_SYSTEMD_UNIT");
179 fprintf(stderr,
"Failed to query journal: %s\n", strerror(-r));
182 SD_JOURNAL_FOREACH_UNIQUE(j, d, l)
183 printf(
"%.*s\n", (int) l, (const char*) d);
191 <title>See Also
</title>
194 <citerefentry><refentrytitle>systemd
</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
195 <citerefentry><refentrytitle>systemd.journal-fields
</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
196 <citerefentry><refentrytitle>sd-journal
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
197 <citerefentry><refentrytitle>sd_journal_open
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
198 <citerefentry><refentrytitle>sd_journal_enumerate_fields
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
199 <citerefentry><refentrytitle>sd_journal_get_data
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
200 <citerefentry><refentrytitle>sd_journal_add_match
</refentrytitle><manvolnum>3</manvolnum></citerefentry>