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>
134 <title>Return Value</title>
136 <para><function>sd_journal_query_unique()</function> returns 0 on
137 success or a negative errno-style error code.
138 <function>sd_journal_enumerate_unique()</function> returns a
139 positive integer if the next field data has been read, 0 when no
140 more fields are known, or a negative errno-style error code.
141 <function>sd_journal_restart_unique()</function> returns
148 <para>The <function>sd_journal_query_unique()</function>,
149 <function>sd_journal_enumerate_unique()</function> and
150 <function>sd_journal_restart_unique()</function> interfaces are
151 available as a shared library, which can be compiled and linked to
153 <constant>libsystemd</constant> <citerefentry project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry>
158 <title>Examples</title>
160 <para>Use the <function>SD_JOURNAL_FOREACH_UNIQUE</function> macro
161 to iterate through all values a field of the journal can take. The
162 following example lists all unit names referenced in the
165 <programlisting>#include <stdio.h>
166 #include <string.h>
167 #include <systemd/sd-journal.h>
169 int main(int argc, char *argv[]) {
175 r = sd_journal_open(&j, SD_JOURNAL_LOCAL_ONLY);
177 fprintf(stderr, "Failed to open journal: %s\n", strerror(-r));
180 r = sd_journal_query_unique(j, "_SYSTEMD_UNIT");
182 fprintf(stderr, "Failed to query journal: %s\n", strerror(-r));
185 SD_JOURNAL_FOREACH_UNIQUE(j, d, l)
186 printf("%.*s\n", (int) l, (const char*) d);
194 <title>See Also</title>
197 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
198 <citerefentry><refentrytitle>systemd.journal-fields</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
199 <citerefentry><refentrytitle>sd-journal</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
200 <citerefentry><refentrytitle>sd_journal_open</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
201 <citerefentry><refentrytitle>sd_journal_get_data</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
202 <citerefentry><refentrytitle>sd_journal_add_match</refentrytitle><manvolnum>3</manvolnum></citerefentry>