[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 '='. Note that this call is subject to the
                data field size threshold as controlled by
                <function>sd_journal_set_data_threshold()</function>.</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
                <constant>libsystemd-journal</constant> <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 void *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, (const char*) 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
93b73b06 LP	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>
1a2be33a LP	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
1e158d27	161	<constant>libsystemd-journal</constant> <citerefentry><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry>
1a2be33a LP	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 <stdio.h>
	175	#include <string.h>
	176	#include <systemd/sd-journal.h>
	177
	178	int main(int argc, char *argv[]) {
	179	sd_journal *j;
0902aa18	180	const void *d;
1a2be33a LP	181	size_t l;
	182	int r;
	183
	184	r = sd_journal_open(&j, SD_JOURNAL_LOCAL_ONLY);
	185	if (r < 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 < 0) {
	191	fprintf(stderr, "Failed to query journal: %s\n", strerror(-r));
	192	return 1;
	193	}
	194	SD_JOURNAL_FOREACH_UNIQUE(j, d, l)
774471b6	195	printf("%.s\n", (int) l, (const char) d);
1a2be33a LP	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>