[thirdparty/systemd.git] / man / sd_journal_query_unique.xml

<?xml version='1.0'?> <!--*-nxml-*-->
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
        "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">

<!--
  This file is part of systemd.

  Copyright 2012 Lennart Poettering

  systemd is free software; you can redistribute it and/or modify it
  under the terms of the GNU Lesser General Public License as published by
  the Free Software Foundation; either version 2.1 of the License, or
  (at your option) any later version.

  systemd is distributed in the hope that it will be useful, but
  WITHOUT ANY WARRANTY; without even the implied warranty of
  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
  Lesser General Public License for more details.

  You should have received a copy of the GNU Lesser General Public License
  along with systemd; If not, see <http://www.gnu.org/licenses/>.
-->

<refentry id="sd_journal_query_unique">

        <refentryinfo>
                <title>sd_journal_query_unique</title>
                <productname>systemd</productname>

                <authorgroup>
                        <author>
                                <contrib>Developer</contrib>
                                <firstname>Lennart</firstname>
                                <surname>Poettering</surname>
                                <email>lennart@poettering.net</email>
                        </author>
                </authorgroup>
        </refentryinfo>

        <refmeta>
                <refentrytitle>sd_journal_query_unique</refentrytitle>
                <manvolnum>3</manvolnum>
        </refmeta>

        <refnamediv>
                <refname>sd_journal_query_unique</refname>
                <refname>sd_journal_enumerate_unique</refname>
                <refname>sd_journal_restart_unique</refname>
                <refname>SD_JOURNAL_FOREACH_UNIQUE</refname>
                <refpurpose>Read unique data fields from the journal</refpurpose>
        </refnamediv>

        <refsynopsisdiv>
                <funcsynopsis>
                        <funcsynopsisinfo>#include &lt;systemd/sd-journal.h&gt;</funcsynopsisinfo>

                        <funcprototype>
                                <funcdef>int <function>sd_journal_query_unique</function></funcdef>
                                <paramdef>sd_journal* <parameter>j</parameter></paramdef>
                                <paramdef>const char* <parameter>field</parameter></paramdef>
                        </funcprototype>

                        <funcprototype>
                                <funcdef>int <function>sd_journal_enumerate_unique</function></funcdef>
                                <paramdef>sd_journal* <parameter>j</parameter></paramdef>
                                <paramdef>const void** <parameter>data</parameter></paramdef>
                                <paramdef>size_t* <parameter>length</parameter></paramdef>
                        </funcprototype>

                        <funcprototype>
                                <funcdef>void <function>sd_journal_restart_unique</function></funcdef>
                                <paramdef>sd_journal* <parameter>j</parameter></paramdef>
                        </funcprototype>

                        <funcprototype>
                                <funcdef><function>SD_JOURNAL_FOREACH_UNIQUE</function></funcdef>
                                <paramdef>sd_journal* <parameter>j</parameter></paramdef>
                                <paramdef>const void* <parameter>data</parameter></paramdef>
                                <paramdef>size_t <parameter>length</parameter></paramdef>
                        </funcprototype>

                </funcsynopsis>
        </refsynopsisdiv>

        <refsect1>
                <title>Description</title>

                <para><function>sd_journal_query_unique()</function>
                queries the journal for all unique values the
                specified field can take. It takes two arguments: the
                journal to query and the field name to look
                for. Well-known field names are listed on
                <citerefentry><refentrytitle>systemd.journal-fields</refentrytitle><manvolnum>7</manvolnum></citerefentry>. Field
                names must be specified without a trailing '='. After
                this function has been executed successfully the field
                values may be queried using
                <function>sd_journal_enumerate_unique()</function>. Invoking
                this call a second time will change the field name
                being queried and reset the enumeration index to the
                first field value that matches.</para>

                <para><function>sd_journal_enumerate_unique()</function>
                may be used to iterate through all data fields which
                match the previously selected field name as set with
                <function>sd_journal_query_unique()</function>. On
                each invocation the next field data matching the field
                name is returned. The order of the returned data
                fields is not defined. It takes three arguments: the
                journal context object, plus a pair of pointers to
                pointer/size variables where the data object and its
                size shall be stored in. The returned data is in a
                read-only memory map and is only valid until the next
                invocation of
                <function>sd_journal_enumerate_unique()</function>. Note
                that the data returned will be prefixed with the field
                name and '='.</para>

                <para><function>sd_journal_restart_unique()</function>
                resets the data enumeration index to the beginning of
                the list. The next invocation of
                <function>sd_journal_enumerate_unique()</function>
                will return the first field data matching the field
                name again.</para>

                <para>Note that the
                <function>SD_JOURNAL_FOREACH_UNIQUE()</function> macro
                may be used as a handy wrapper around
                <function>sd_journal_restart_unique()</function> and
                <function>sd_journal_enumerate_unique()</function>.</para>

                <para>Note that these functions currently are not
                influenced by matches set with
                <function>sd_journal_add_match()</function> but this
                might change in a later version of this
                software.</para>
        </refsect1>

        <refsect1>
                <title>Return Value</title>

                <para><function>sd_journal_query_unique()</function>
                returns 0 on success or a negative errno-style error
                code. <function>sd_journal_enumerate_unique()</function>
                returns a positive integer if the next field data has
                been read, 0 when no more fields are known, or a
                negative errno-style error
                code. <function>sd_journal_restart_unique()</function>
                returns nothing.</para>
        </refsect1>

        <refsect1>
                <title>Notes</title>

                <para>The <function>sd_journal_query_unique()</function>,
                <function>sd_journal_enumerate_unique()</function> and
                <function>sd_journal_restart_unique()</function>
                interfaces are available as shared library, which can
                be compiled and linked to with the
                <literal>libsystemd-journal</literal>
                <citerefentry><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry>
                file.</para>
        </refsect1>

        <refsect1>
                <title>Examples</title>

                <para>Use the
                <function>SD_JOURNAL_FOREACH_UNIQUE</function> macro
                to iterate through all values a field of the journal
                can take. The following example lists all unit names
                referenced in the journal:</para>

                <programlisting>#include &lt;stdio.h&gt;
#include &lt;string.h&gt;
#include &lt;systemd/sd-journal.h&gt;

int main(int argc, char *argv[]) {
        sd_journal *j;
        const char *d;
        size_t l;
        int r;

        r = sd_journal_open(&amp;j, SD_JOURNAL_LOCAL_ONLY);
        if (r &lt; 0) {
                fprintf(stderr, "Failed to open journal: %s\n", strerror(-r));
                return 1;
        }
        r = sd_journal_query_unique(j, "_SYSTEMD_UNIT");
        if (r &lt; 0) {
                fprintf(stderr, "Failed to query journal: %s\n", strerror(-r));
                return 1;
        }
        SD_JOURNAL_FOREACH_UNIQUE(j, d, l)
                printf("%.*s\n", (int) l, d);
        sd_journal_close(j);
        return 0;
}</programlisting>

        </refsect1>

        <refsect1>
                <title>See Also</title>

                <para>
                        <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
                        <citerefentry><refentrytitle>systemd.journal-fields</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
                        <citerefentry><refentrytitle>sd-journal</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
                        <citerefentry><refentrytitle>sd_journal_open</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
                        <citerefentry><refentrytitle>sd_journal_get_data</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
                        <citerefentry><refentrytitle>sd_journal_add_match</refentrytitle><manvolnum>3</manvolnum></citerefentry>
                </para>
        </refsect1>

</refentry>
Commit	Line	Data
1a2be33a LP	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 <systemd/sd-journal.h></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 '='.</para>
117
118	<para><function>sd_journal_restart_unique()</function>
119	resets the data enumeration index to the beginning of
120	the list. The next invocation of
121	<function>sd_journal_enumerate_unique()</function>
122	will return the first field data matching the field
123	name again.</para>
124
125	<para>Note that the
126	<function>SD_JOURNAL_FOREACH_UNIQUE()</function> macro
127	may be used as a handy wrapper around
128	<function>sd_journal_restart_unique()</function> and
129	<function>sd_journal_enumerate_unique()</function>.</para>
130
131	<para>Note that these functions currently are not
132	influenced by matches set with
133	<function>sd_journal_add_match()</function> but this
134	might change in a later version of this
135	software.</para>
136	</refsect1>
137
138	<refsect1>
139	<title>Return Value</title>
140
141	<para><function>sd_journal_query_unique()</function>
142	returns 0 on success or a negative errno-style error
143	code. <function>sd_journal_enumerate_unique()</function>
144	returns a positive integer if the next field data has
145	been read, 0 when no more fields are known, or a
146	negative errno-style error
147	code. <function>sd_journal_restart_unique()</function>
148	returns nothing.</para>
149	</refsect1>
150
151	<refsect1>
152	<title>Notes</title>
153
154	<para>The <function>sd_journal_query_unique()</function>,
155	<function>sd_journal_enumerate_unique()</function> and
156	<function>sd_journal_restart_unique()</function>
157	interfaces are available as shared library, which can
158	be compiled and linked to with the
159	<literal>libsystemd-journal</literal>
160	<citerefentry><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry>
161	file.</para>
162	</refsect1>
163
164	<refsect1>
165	<title>Examples</title>
166
167	<para>Use the
168	<function>SD_JOURNAL_FOREACH_UNIQUE</function> macro
169	to iterate through all values a field of the journal
170	can take. The following example lists all unit names
171	referenced in the journal:</para>
172
173	<programlisting>#include <stdio.h>
174	#include <string.h>
175	#include <systemd/sd-journal.h>
176
177	int main(int argc, char *argv[]) {
178	sd_journal *j;
179	const char *d;
180	size_t l;
181	int r;
182
183	r = sd_journal_open(&j, SD_JOURNAL_LOCAL_ONLY);
184	if (r < 0) {
185	fprintf(stderr, "Failed to open journal: %s\n", strerror(-r));
186	return 1;
187	}
188	r = sd_journal_query_unique(j, "_SYSTEMD_UNIT");
189	if (r < 0) {
190	fprintf(stderr, "Failed to query journal: %s\n", strerror(-r));
191	return 1;
192	}
193	SD_JOURNAL_FOREACH_UNIQUE(j, d, l)
194	printf("%.*s\n", (int) l, d);
195	sd_journal_close(j);
196	return 0;
197	}</programlisting>
198
199	</refsect1>
200
201	<refsect1>
202	<title>See Also</title>
203
204	<para>
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_get_data</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
210	<citerefentry><refentrytitle>sd_journal_add_match</refentrytitle><manvolnum>3</manvolnum></citerefentry>
211	</para>
212	</refsect1>
213
214	</refentry>