chiark / gitweb /
man: update sd_bus_request_name() man page
[elogind.git] / man / sd_journal_query_unique.xml
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">
4
5 <!--
6   This file is part of systemd.
7
8   Copyright 2012 Lennart Poettering
9
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.
14
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.
19
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/>.
22 -->
23
24 <refentry id="sd_journal_query_unique">
25
26         <refentryinfo>
27                 <title>sd_journal_query_unique</title>
28                 <productname>systemd</productname>
29
30                 <authorgroup>
31                         <author>
32                                 <contrib>Developer</contrib>
33                                 <firstname>Lennart</firstname>
34                                 <surname>Poettering</surname>
35                                 <email>lennart@poettering.net</email>
36                         </author>
37                 </authorgroup>
38         </refentryinfo>
39
40         <refmeta>
41                 <refentrytitle>sd_journal_query_unique</refentrytitle>
42                 <manvolnum>3</manvolnum>
43         </refmeta>
44
45         <refnamediv>
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>
51         </refnamediv>
52
53         <refsynopsisdiv>
54                 <funcsynopsis>
55                         <funcsynopsisinfo>#include &lt;systemd/sd-journal.h&gt;</funcsynopsisinfo>
56
57                         <funcprototype>
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>
61                         </funcprototype>
62
63                         <funcprototype>
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>
68                         </funcprototype>
69
70                         <funcprototype>
71                                 <funcdef>void <function>sd_journal_restart_unique</function></funcdef>
72                                 <paramdef>sd_journal* <parameter>j</parameter></paramdef>
73                         </funcprototype>
74
75                         <funcprototype>
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>
80                         </funcprototype>
81
82                 </funcsynopsis>
83         </refsynopsisdiv>
84
85         <refsect1>
86                 <title>Description</title>
87
88                 <para><function>sd_journal_query_unique()</function>
89                 queries the journal for all unique values the
90                 specified field can take. It takes two arguments: the
91                 journal to query and the field name to look
92                 for. Well-known field names are listed on
93                 <citerefentry><refentrytitle>systemd.journal-fields</refentrytitle><manvolnum>7</manvolnum></citerefentry>. Field
94                 names must be specified without a trailing '='. After
95                 this function has been executed successfully the field
96                 values may be queried using
97                 <function>sd_journal_enumerate_unique()</function>. Invoking
98                 this call a second time will change the field name
99                 being queried and reset the enumeration index to the
100                 first field value that matches.</para>
101
102                 <para><function>sd_journal_enumerate_unique()</function>
103                 may be used to iterate through all data fields which
104                 match the previously selected field name as set with
105                 <function>sd_journal_query_unique()</function>. On
106                 each invocation the next field data matching the field
107                 name is returned. The order of the returned data
108                 fields is not defined. It takes three arguments: the
109                 journal context object, plus a pair of pointers to
110                 pointer/size variables where the data object and its
111                 size shall be stored in. The returned data is in a
112                 read-only memory map and is only valid until the next
113                 invocation of
114                 <function>sd_journal_enumerate_unique()</function>. Note
115                 that the data returned will be prefixed with the field
116                 name and '='. Note that this call is subject to the
117                 data field size threshold as controlled by
118                 <function>sd_journal_set_data_threshold()</function>.</para>
119
120                 <para><function>sd_journal_restart_unique()</function>
121                 resets the data enumeration index to the beginning of
122                 the list. The next invocation of
123                 <function>sd_journal_enumerate_unique()</function>
124                 will return the first field data matching the field
125                 name again.</para>
126
127                 <para>Note that the
128                 <function>SD_JOURNAL_FOREACH_UNIQUE()</function> macro
129                 may be used as a handy wrapper around
130                 <function>sd_journal_restart_unique()</function> and
131                 <function>sd_journal_enumerate_unique()</function>.</para>
132
133                 <para>Note that these functions currently are not
134                 influenced by matches set with
135                 <function>sd_journal_add_match()</function> but this
136                 might change in a later version of this
137                 software.</para>
138         </refsect1>
139
140         <refsect1>
141                 <title>Return Value</title>
142
143                 <para><function>sd_journal_query_unique()</function>
144                 returns 0 on success or a negative errno-style error
145                 code. <function>sd_journal_enumerate_unique()</function>
146                 returns a positive integer if the next field data has
147                 been read, 0 when no more fields are known, or a
148                 negative errno-style error
149                 code. <function>sd_journal_restart_unique()</function>
150                 returns nothing.</para>
151         </refsect1>
152
153         <refsect1>
154                 <title>Notes</title>
155
156                 <para>The <function>sd_journal_query_unique()</function>,
157                 <function>sd_journal_enumerate_unique()</function> and
158                 <function>sd_journal_restart_unique()</function>
159                 interfaces are available as shared library, which can
160                 be compiled and linked to with the
161                 <constant>libsystemd-journal</constant> <citerefentry><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry>
162                 file.</para>
163         </refsect1>
164
165         <refsect1>
166                 <title>Examples</title>
167
168                 <para>Use the
169                 <function>SD_JOURNAL_FOREACH_UNIQUE</function> macro
170                 to iterate through all values a field of the journal
171                 can take. The following example lists all unit names
172                 referenced in the journal:</para>
173
174                 <programlisting>#include &lt;stdio.h&gt;
175 #include &lt;string.h&gt;
176 #include &lt;systemd/sd-journal.h&gt;
177
178 int main(int argc, char *argv[]) {
179         sd_journal *j;
180         const void *d;
181         size_t l;
182         int r;
183
184         r = sd_journal_open(&amp;j, SD_JOURNAL_LOCAL_ONLY);
185         if (r &lt; 0) {
186                 fprintf(stderr, "Failed to open journal: %s\n", strerror(-r));
187                 return 1;
188         }
189         r = sd_journal_query_unique(j, "_SYSTEMD_UNIT");
190         if (r &lt; 0) {
191                 fprintf(stderr, "Failed to query journal: %s\n", strerror(-r));
192                 return 1;
193         }
194         SD_JOURNAL_FOREACH_UNIQUE(j, d, l)
195                 printf("%.*s\n", (int) l, (const char*) d);
196         sd_journal_close(j);
197         return 0;
198 }</programlisting>
199
200         </refsect1>
201
202         <refsect1>
203                 <title>See Also</title>
204
205                 <para>
206                         <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
207                         <citerefentry><refentrytitle>systemd.journal-fields</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
208                         <citerefentry><refentrytitle>sd-journal</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
209                         <citerefentry><refentrytitle>sd_journal_open</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>
212                 </para>
213         </refsect1>
214
215 </refentry>