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 This file is part of systemd.
8 Copyright 2012 Lennart Poettering
10 systemd is free software; you can redistribute it and/or modify it
11 under the terms of the GNU Lesser General Public License as published by
12 the Free Software Foundation; either version 2.1 of the License, or
13 (at your option) any later version.
15 systemd is distributed in the hope that it will be useful, but
16 WITHOUT ANY WARRANTY; without even the implied warranty of
17 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
18 Lesser General Public License for more details.
20 You should have received a copy of the GNU Lesser General Public License
21 along with systemd; If not, see <http://www.gnu.org/licenses/>.
24 <refentry id=
"sd_journal_query_unique">
27 <title>sd_journal_query_unique
</title>
28 <productname>systemd
</productname>
32 <contrib>Developer
</contrib>
33 <firstname>Lennart
</firstname>
34 <surname>Poettering
</surname>
35 <email>lennart@poettering.net
</email>
41 <refentrytitle>sd_journal_query_unique
</refentrytitle>
42 <manvolnum>3</manvolnum>
46 <refname>sd_journal_query_unique
</refname>
47 <refname>sd_journal_enumerate_unique
</refname>
48 <refname>sd_journal_restart_unique
</refname>
49 <refname>SD_JOURNAL_FOREACH_UNIQUE
</refname>
50 <refpurpose>Read unique data fields from the journal
</refpurpose>
55 <funcsynopsisinfo>#include
<systemd/sd-journal.h
></funcsynopsisinfo>
58 <funcdef>int
<function>sd_journal_query_unique
</function></funcdef>
59 <paramdef>sd_journal *
<parameter>j
</parameter></paramdef>
60 <paramdef>const char *
<parameter>field
</parameter></paramdef>
64 <funcdef>int
<function>sd_journal_enumerate_unique
</function></funcdef>
65 <paramdef>sd_journal *
<parameter>j
</parameter></paramdef>
66 <paramdef>const void **
<parameter>data
</parameter></paramdef>
67 <paramdef>size_t *
<parameter>length
</parameter></paramdef>
71 <funcdef>void
<function>sd_journal_restart_unique
</function></funcdef>
72 <paramdef>sd_journal *
<parameter>j
</parameter></paramdef>
76 <funcdef><function>SD_JOURNAL_FOREACH_UNIQUE
</function></funcdef>
77 <paramdef>sd_journal *
<parameter>j
</parameter></paramdef>
78 <paramdef>const void *
<parameter>data
</parameter></paramdef>
79 <paramdef>size_t
<parameter>length
</parameter></paramdef>
86 <title>Description
</title>
88 <para><function>sd_journal_query_unique()
</function> queries the
89 journal for all unique values the specified field can take. It
90 takes two arguments: the journal to query and the field name to
91 look for. Well-known field names are listed on
92 <citerefentry><refentrytitle>systemd.journal-fields
</refentrytitle><manvolnum>7</manvolnum></citerefentry>.
93 Field names must be specified without a trailing '='. After this
94 function has been executed successfully the field values may be
95 queried using
<function>sd_journal_enumerate_unique()
</function>.
96 Invoking this call a second time will change the field name being
97 queried and reset the enumeration index to the first field value
100 <para><function>sd_journal_enumerate_unique()
</function> may be
101 used to iterate through all data fields which match the previously
102 selected field name as set with
103 <function>sd_journal_query_unique()
</function>. On each invocation
104 the next field data matching the field name is returned. The order
105 of the returned data fields is not defined. It takes three
106 arguments: the journal context object, plus a pair of pointers to
107 pointer/size variables where the data object and its size shall be
108 stored in. The returned data is in a read-only memory map and is
109 only valid until the next invocation of
110 <function>sd_journal_enumerate_unique()
</function>. Note that the
111 data returned will be prefixed with the field name and '='. Note
112 that this call is subject to the data field size threshold as
114 <function>sd_journal_set_data_threshold()
</function>.
</para>
116 <para><function>sd_journal_restart_unique()
</function> resets the
117 data enumeration index to the beginning of the list. The next
118 invocation of
<function>sd_journal_enumerate_unique()
</function>
119 will return the first field data matching the field name
123 <function>SD_JOURNAL_FOREACH_UNIQUE()
</function> macro may be used
124 as a handy wrapper around
125 <function>sd_journal_restart_unique()
</function> and
126 <function>sd_journal_enumerate_unique()
</function>.
</para>
128 <para>Note that these functions currently are not influenced by
129 matches set with
<function>sd_journal_add_match()
</function> but
130 this might change in a later version of this software.
</para>
132 <para>To enumerate all field names currently in use (and thus all suitable field parameters for
133 <function>sd_journal_query_unique()
</function>), use the
134 <citerefentry><refentrytitle>sd_journal_enumerate_fields
</refentrytitle><manvolnum>3</manvolnum></citerefentry>
139 <title>Return Value
</title>
141 <para><function>sd_journal_query_unique()
</function> returns
0 on
142 success or a negative errno-style error code.
143 <function>sd_journal_enumerate_unique()
</function> returns a
144 positive integer if the next field data has been read,
0 when no
145 more fields are known, or a negative errno-style error code.
146 <function>sd_journal_restart_unique()
</function> returns
153 <para>All functions listed here are thread-agnostic and only a single thread may operate
154 on a given
<structname>sd_journal
</structname> object.
</para>
156 <para>The
<function>sd_journal_query_unique()
</function>,
157 <function>sd_journal_enumerate_unique()
</function> and
158 <function>sd_journal_restart_unique()
</function> interfaces are
159 available as a shared library, which can be compiled and linked to
161 <constant>libsystemd
</constant> <citerefentry project='die-net'
><refentrytitle>pkg-config
</refentrytitle><manvolnum>1</manvolnum></citerefentry>
166 <title>Examples
</title>
168 <para>Use the
<function>SD_JOURNAL_FOREACH_UNIQUE
</function> macro
169 to iterate through all values a field of the journal can take. The
170 following example lists all unit names referenced in the
173 <programlisting>#include
<stdio.h
>
174 #include
<string.h
>
175 #include
<systemd/sd-journal.h
>
177 int main(int argc, char *argv[]) {
183 r = sd_journal_open(
&j, SD_JOURNAL_LOCAL_ONLY);
185 fprintf(stderr,
"Failed to open journal: %s\n", strerror(-r));
188 r = sd_journal_query_unique(j,
"_SYSTEMD_UNIT");
190 fprintf(stderr,
"Failed to query journal: %s\n", strerror(-r));
193 SD_JOURNAL_FOREACH_UNIQUE(j, d, l)
194 printf(
"%.*s\n", (int) l, (const char*) d);
202 <title>See Also
</title>
205 <citerefentry><refentrytitle>systemd
</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
206 <citerefentry><refentrytitle>systemd.journal-fields
</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
207 <citerefentry><refentrytitle>sd-journal
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
208 <citerefentry><refentrytitle>sd_journal_open
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
209 <citerefentry><refentrytitle>sd_journal_enumerate_fields
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
210 <citerefentry><refentrytitle>sd_journal_get_data
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
211 <citerefentry><refentrytitle>sd_journal_add_match
</refentrytitle><manvolnum>3</manvolnum></citerefentry>