X-Git-Url: https://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?a=blobdiff_plain;f=man%2Fsd_journal_query_unique.xml;h=ac0e5f633f30fcebb4f1d704fa05e0a53811ae14;hb=07a0d22f9ec5a0cac2385b73dc08b12a811cead8;hp=278506ae19ad4c0310b1390d2bb60cff0d450acc;hpb=1a2be33aa584df0d2fe8fa30d35b7c04eb092920;p=elogind.git

diff --git a/man/sd_journal_query_unique.xml b/man/sd_journal_query_unique.xml
index 278506ae1..ac0e5f633 100644
--- a/man/sd_journal_query_unique.xml
+++ b/man/sd_journal_query_unique.xml
@@ -1,6 +1,6 @@
 <?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">
+  "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
 
 <!--
   This file is part of systemd.
@@ -23,192 +23,184 @@
 
 <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;
+  <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 project='die-net'><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;
+  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>
 
-        <refsect1>
-                <title>See Also</title>
+  <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>
+    <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>