2012-10-18 20:48:45 +04:00
<?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: / / w w w . g n u . o r g / l i c e n s e s /> .
-->
<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 < systemd/sd-journal.h> </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
2012-11-21 03:28:00 +04:00
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>
2012-10-18 20:48:45 +04:00
<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
2013-06-27 20:38:15 +04:00
<constant > libsystemd-journal</constant> <citerefentry > <refentrytitle > pkg-config</refentrytitle> <manvolnum > 1</manvolnum> </citerefentry>
2012-10-18 20:48:45 +04:00
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 < stdio.h>
#include < string.h>
#include < systemd/sd-journal.h>
int main(int argc, char *argv[]) {
sd_journal *j;
2012-10-19 00:54:58 +04:00
const void *d;
2012-10-18 20:48:45 +04:00
size_t l;
int r;
r = sd_journal_open(& j, SD_JOURNAL_LOCAL_ONLY);
if (r < 0) {
fprintf(stderr, "Failed to open journal: %s\n", strerror(-r));
return 1;
}
r = sd_journal_query_unique(j, "_SYSTEMD_UNIT");
if (r < 0) {
fprintf(stderr, "Failed to query journal: %s\n", strerror(-r));
return 1;
}
SD_JOURNAL_FOREACH_UNIQUE(j, d, l)
2012-10-19 01:34:38 +04:00
printf("%.*s\n", (int) l, (const char*) d);
2012-10-18 20:48:45 +04:00
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>
