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
12 systemd is free software; you can redistribute it and/or modify it
13 under the terms of the GNU Lesser General Public License as published by
14 the Free Software Foundation; either version 2.1 of the License, or
15 (at your option) any later version.
17 systemd is distributed in the hope that it will be useful, but
18 WITHOUT ANY WARRANTY; without even the implied warranty of
19 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
20 Lesser General Public License for more details.
22 You should have received a copy of the GNU Lesser General Public License
23 along with systemd; If not, see <http://www.gnu.org/licenses/>.
26 <refentry id=
"sd_journal_query_unique">
29 <title>sd_journal_query_unique
</title>
30 <productname>systemd
</productname>
34 <contrib>Developer
</contrib>
35 <firstname>Lennart
</firstname>
36 <surname>Poettering
</surname>
37 <email>lennart@poettering.net
</email>
43 <refentrytitle>sd_journal_query_unique
</refentrytitle>
44 <manvolnum>3</manvolnum>
48 <refname>sd_journal_query_unique
</refname>
49 <refname>sd_journal_enumerate_unique
</refname>
50 <refname>sd_journal_restart_unique
</refname>
51 <refname>SD_JOURNAL_FOREACH_UNIQUE
</refname>
52 <refpurpose>Read unique data fields from the journal
</refpurpose>
57 <funcsynopsisinfo>#include
<systemd/sd-journal.h
></funcsynopsisinfo>
60 <funcdef>int
<function>sd_journal_query_unique
</function></funcdef>
61 <paramdef>sd_journal *
<parameter>j
</parameter></paramdef>
62 <paramdef>const char *
<parameter>field
</parameter></paramdef>
66 <funcdef>int
<function>sd_journal_enumerate_unique
</function></funcdef>
67 <paramdef>sd_journal *
<parameter>j
</parameter></paramdef>
68 <paramdef>const void **
<parameter>data
</parameter></paramdef>
69 <paramdef>size_t *
<parameter>length
</parameter></paramdef>
73 <funcdef>void
<function>sd_journal_restart_unique
</function></funcdef>
74 <paramdef>sd_journal *
<parameter>j
</parameter></paramdef>
78 <funcdef><function>SD_JOURNAL_FOREACH_UNIQUE
</function></funcdef>
79 <paramdef>sd_journal *
<parameter>j
</parameter></paramdef>
80 <paramdef>const void *
<parameter>data
</parameter></paramdef>
81 <paramdef>size_t
<parameter>length
</parameter></paramdef>
88 <title>Description
</title>
90 <para><function>sd_journal_query_unique()
</function> queries the
91 journal for all unique values the specified field can take. It
92 takes two arguments: the journal to query and the field name to
93 look for. Well-known field names are listed on
94 <citerefentry><refentrytitle>systemd.journal-fields
</refentrytitle><manvolnum>7</manvolnum></citerefentry>.
95 Field names must be specified without a trailing '='. After this
96 function has been executed successfully the field values may be
97 queried using
<function>sd_journal_enumerate_unique()
</function>.
98 Invoking this call a second time will change the field name being
99 queried and reset the enumeration index to the first field value
102 <para><function>sd_journal_enumerate_unique()
</function> may be
103 used to iterate through all data fields which match the previously
104 selected field name as set with
105 <function>sd_journal_query_unique()
</function>. On each invocation
106 the next field data matching the field name is returned. The order
107 of the returned data fields is not defined. It takes three
108 arguments: the journal context object, plus a pair of pointers to
109 pointer/size variables where the data object and its size shall be
110 stored in. The returned data is in a read-only memory map and is
111 only valid until the next invocation of
112 <function>sd_journal_enumerate_unique()
</function>. Note that the
113 data returned will be prefixed with the field name and '='. Note
114 that this call is subject to the data field size threshold as
116 <function>sd_journal_set_data_threshold()
</function>.
</para>
118 <para><function>sd_journal_restart_unique()
</function> resets the
119 data enumeration index to the beginning of the list. The next
120 invocation of
<function>sd_journal_enumerate_unique()
</function>
121 will return the first field data matching the field name
125 <function>SD_JOURNAL_FOREACH_UNIQUE()
</function> macro may be used
126 as a handy wrapper around
127 <function>sd_journal_restart_unique()
</function> and
128 <function>sd_journal_enumerate_unique()
</function>.
</para>
130 <para>Note that these functions currently are not influenced by
131 matches set with
<function>sd_journal_add_match()
</function> but
132 this might change in a later version of this software.
</para>
134 <para>To enumerate all field names currently in use (and thus all suitable field parameters for
135 <function>sd_journal_query_unique()
</function>), use the
136 <citerefentry><refentrytitle>sd_journal_enumerate_fields
</refentrytitle><manvolnum>3</manvolnum></citerefentry>
141 <title>Return Value
</title>
143 <para><function>sd_journal_query_unique()
</function> returns
0 on
144 success or a negative errno-style error code.
145 <function>sd_journal_enumerate_unique()
</function> returns a
146 positive integer if the next field data has been read,
0 when no
147 more fields are known, or a negative errno-style error code.
148 <function>sd_journal_restart_unique()
</function> returns
155 <para>All functions listed here are thread-agnostic and only a single thread may operate
156 on a given
<structname>sd_journal
</structname> object.
</para>
158 <para>The
<function>sd_journal_query_unique()
</function>,
159 <function>sd_journal_enumerate_unique()
</function> and
160 <function>sd_journal_restart_unique()
</function> interfaces are
161 available as a shared library, which can be compiled and linked to
163 <constant>libsystemd
</constant> <citerefentry project='die-net'
><refentrytitle>pkg-config
</refentrytitle><manvolnum>1</manvolnum></citerefentry>
168 <title>Examples
</title>
170 <para>Use the
<function>SD_JOURNAL_FOREACH_UNIQUE
</function> macro
171 to iterate through all values a field of the journal can take. The
172 following example lists all unit names referenced in the
175 <programlisting>#include
<stdio.h
>
176 #include
<string.h
>
177 #include
<systemd/sd-journal.h
>
179 int main(int argc, char *argv[]) {
185 r = sd_journal_open(
&j, SD_JOURNAL_LOCAL_ONLY);
187 fprintf(stderr,
"Failed to open journal: %s\n", strerror(-r));
190 r = sd_journal_query_unique(j,
"_SYSTEMD_UNIT");
192 fprintf(stderr,
"Failed to query journal: %s\n", strerror(-r));
195 SD_JOURNAL_FOREACH_UNIQUE(j, d, l)
196 printf(
"%.*s\n", (int) l, (const char*) d);
204 <title>See Also
</title>
207 <citerefentry><refentrytitle>systemd
</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
208 <citerefentry><refentrytitle>systemd.journal-fields
</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
209 <citerefentry><refentrytitle>sd-journal
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
210 <citerefentry><refentrytitle>sd_journal_open
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
211 <citerefentry><refentrytitle>sd_journal_enumerate_fields
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
212 <citerefentry><refentrytitle>sd_journal_get_data
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
213 <citerefentry><refentrytitle>sd_journal_add_match
</refentrytitle><manvolnum>3</manvolnum></citerefentry>