shaba/systemd
1
0
Fork 0
mirror of https://github.com/systemd/systemd.git synced 2024-11-06 16:59:03 +03:00
Code
e30fa16e27
systemd/man/sd_journal_query_unique.xml

216 lines
9.8 KiB
XML
Raw Blame History

This file contains invisible Unicode characters

This file contains invisible Unicode characters that are indistinguishable to humans but may be processed differently by a computer. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

<?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 a shared library, which can
be compiled and linked to with the
<constant>libsystemd</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>
View Git Blame Copy Permalink