X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?p=elogind.git;a=blobdiff_plain;f=man%2Fsd_journal_next.xml;h=115fe26661cc1b003be1ef081a15f1d5827b9e28;hp=f55ee157444f5d954f11f4de84fe4a879a8c1223;hb=418761f5864fe1ae7e9bb884259cc9933ae8ad0c;hpb=67c3cf4f9ea35c1f789526b24a4d052d071902c0

diff --git a/man/sd_journal_next.xml b/man/sd_journal_next.xml
index f55ee1574..115fe2666 100644
--- a/man/sd_journal_next.xml
+++ b/man/sd_journal_next.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,172 +23,185 @@
 
 <refentry id="sd_journal_next">
 
-        <refentryinfo>
-                <title>sd_journal_next</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_next</refentrytitle>
-                <manvolnum>3</manvolnum>
-        </refmeta>
-
-        <refnamediv>
-                <refname>sd_journal_next</refname>
-                <refname>sd_journal_previous</refname>
-                <refname>sd_journal_next_skip</refname>
-                <refname>sd_journal_previous_skip</refname>
-                <refpurpose>Advance or set back the read pointer in the journal</refpurpose>
-        </refnamediv>
-
-        <refsynopsisdiv>
-                <funcsynopsis>
-                        <funcsynopsisinfo>#include &lt;systemd/sd-journal.h&gt;</funcsynopsisinfo>
-
-                        <funcprototype>
-                                <funcdef>int <function>sd_journal_next</function></funcdef>
-                                <paramdef>sd_journal* <parameter>j</parameter></paramdef>
-                        </funcprototype>
-
-                        <funcprototype>
-                                <funcdef>int <function>sd_journal_previous</function></funcdef>
-                                <paramdef>sd_journal* <parameter>j</parameter></paramdef>
-                        </funcprototype>
-
-                        <funcprototype>
-                                <funcdef>int <function>sd_journal_next_skip</function></funcdef>
-                                <paramdef>sd_journal* <parameter>j</parameter></paramdef>
-                                <paramdef>uint64_t <parameter>skip</parameter></paramdef>
-                        </funcprototype>
-
-                        <funcprototype>
-                                <funcdef>int <function>sd_journal_previous_skip</function></funcdef>
-                                <paramdef>sd_journal* <parameter>j</parameter></paramdef>
-                                <paramdef>uint64_t <parameter>skip</parameter></paramdef>
-                        </funcprototype>
-
-                </funcsynopsis>
-        </refsynopsisdiv>
-
-        <refsect1>
-                <title>Description</title>
-
-                <para><function>sd_journal_next()</function> advances
-                the read pointer into the journal by one entry. The
-                only argument taken is a journal context object as
-                allocated via
-                <citerefentry><refentrytitle>sd_journal_open</refentrytitle><manvolnum>3</manvolnum></citerefentry>. After
-                successful invocation the entry may be read with
-                functions such as
-                <citerefentry><refentrytitle>sd_journal_get_data</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para>
-
-                <para>Similar, <function>sd_journal_previous()</function> sets
-                the read pointer back one entry.</para>
-
-                <para><function>sd_journal_next_skip()</function> and
-                <function>sd_journal_previous_skip()</function>
-                advance/set back the read pointer by multiple entries
-                at once, as specified in the <varname>skip</varname>
-                parameter.</para>
-
-                <para>The journal is strictly ordered by reception
-                time, and hence advancing to the next entry guarantees
-                that the entry then pointing to is later in time than
-                then previous one, or has the same timestamp.</para>
-
-                <para>Note that the
-                <function>SD_JOURNAL_FOREACH()</function> macro may be used
-                as a wrapper around
-                <citerefentry><refentrytitle>sd_journal_seek_head</refentrytitle><manvolnum>3</manvolnum></citerefentry>
-                and <function>sd_journal_next()</function> in order to
-                make iteratring through the journal easier. See below
-                for an example. Similar,
-                <function>SD_JOURNAL_FOREACH_BACKWARDS()</function>
-                may be used for iterating the journal in reverse
-                order.</para>
-        </refsect1>
-
-        <refsect1>
-                <title>Return Value</title>
-
-                <para>The four calls return the number of entries
-                advanced/set back on success or a negative errno-style
-                error code. When the end (resp. beginning) of the journal
-                is reached a number smaller than requested is
-                returned. More specifically, if
-                <function>sd_journal_next()</function> or
-                <function>sd_journal_previous()</function> reach the
-                end/beginning of the journal they will return 0,
-                instead of 1 when they are successful. This should be
-                considered an EOF marker.</para>
-        </refsect1>
-
-        <refsect1>
-                <title>Notes</title>
-
-                <para>The <function>sd_journal_next()</function>, <function>sd_journal_previous()</function>,
-                <function>sd_journal_next_skip()</function> and
-                <function>sd_journal_previous_skip()</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>Iterating through the journal:</para>
-
-                <programlisting>#include &lt;stdio.h&gt;
+  <refentryinfo>
+    <title>sd_journal_next</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_next</refentrytitle>
+    <manvolnum>3</manvolnum>
+  </refmeta>
+
+  <refnamediv>
+    <refname>sd_journal_next</refname>
+    <refname>sd_journal_previous</refname>
+    <refname>sd_journal_next_skip</refname>
+    <refname>sd_journal_previous_skip</refname>
+    <refname>SD_JOURNAL_FOREACH</refname>
+    <refname>SD_JOURNAL_FOREACH_BACKWARDS</refname>
+    <refpurpose>Advance or set back the read pointer in the journal</refpurpose>
+  </refnamediv>
+
+  <refsynopsisdiv>
+    <funcsynopsis>
+      <funcsynopsisinfo>#include &lt;systemd/sd-journal.h&gt;</funcsynopsisinfo>
+
+      <funcprototype>
+        <funcdef>int <function>sd_journal_next</function></funcdef>
+        <paramdef>sd_journal *<parameter>j</parameter></paramdef>
+      </funcprototype>
+
+      <funcprototype>
+        <funcdef>int <function>sd_journal_previous</function></funcdef>
+        <paramdef>sd_journal *<parameter>j</parameter></paramdef>
+      </funcprototype>
+
+      <funcprototype>
+        <funcdef>int <function>sd_journal_next_skip</function></funcdef>
+        <paramdef>sd_journal *<parameter>j</parameter></paramdef>
+        <paramdef>uint64_t <parameter>skip</parameter></paramdef>
+      </funcprototype>
+
+      <funcprototype>
+        <funcdef>int <function>sd_journal_previous_skip</function></funcdef>
+        <paramdef>sd_journal *<parameter>j</parameter></paramdef>
+        <paramdef>uint64_t <parameter>skip</parameter></paramdef>
+      </funcprototype>
+
+      <funcprototype>
+        <funcdef><function>SD_JOURNAL_FOREACH</function></funcdef>
+        <paramdef>sd_journal *<parameter>j</parameter></paramdef>
+      </funcprototype>
+
+      <funcprototype>
+        <funcdef><function>SD_JOURNAL_FOREACH_BACKWARDS</function></funcdef>
+        <paramdef>sd_journal *<parameter>j</parameter></paramdef>
+      </funcprototype>
+    </funcsynopsis>
+  </refsynopsisdiv>
+
+  <refsect1>
+    <title>Description</title>
+
+    <para><function>sd_journal_next()</function> advances the read
+    pointer into the journal by one entry. The only argument taken is
+    a journal context object as allocated via
+    <citerefentry><refentrytitle>sd_journal_open</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
+    After successful invocation the entry may be read with functions
+    such as
+    <citerefentry><refentrytitle>sd_journal_get_data</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para>
+
+    <para>Similarly, <function>sd_journal_previous()</function> sets
+    the read pointer back one entry.</para>
+
+    <para><function>sd_journal_next_skip()</function> and
+    <function>sd_journal_previous_skip()</function> advance/set back
+    the read pointer by multiple entries at once, as specified in the
+    <varname>skip</varname> parameter.</para>
+
+    <para>The journal is strictly ordered by reception time, and hence
+    advancing to the next entry guarantees that the entry then
+    pointing to is later in time than then previous one, or has the
+    same timestamp.</para>
+
+    <para>Note that
+    <citerefentry><refentrytitle>sd_journal_get_data</refentrytitle><manvolnum>3</manvolnum></citerefentry>
+    and related calls will fail unless
+    <function>sd_journal_next()</function> has been invoked at least
+    once in order to position the read pointer on a journal
+    entry.</para>
+
+    <para>Note that the <function>SD_JOURNAL_FOREACH()</function>
+    macro may be used as a wrapper around
+    <citerefentry><refentrytitle>sd_journal_seek_head</refentrytitle><manvolnum>3</manvolnum></citerefentry>
+    and <function>sd_journal_next()</function> in order to make
+    iterating through the journal easier. See below for an example.
+    Similarly, <function>SD_JOURNAL_FOREACH_BACKWARDS()</function> may
+    be used for iterating the journal in reverse order.</para>
+  </refsect1>
+
+  <refsect1>
+    <title>Return Value</title>
+
+    <para>The four calls return the number of entries advanced/set
+    back on success or a negative errno-style error code. When the end
+    or beginning of the journal is reached, a number smaller than
+    requested is returned. More specifically, if
+    <function>sd_journal_next()</function> or
+    <function>sd_journal_previous()</function> reach the end/beginning
+    of the journal they will return 0, instead of 1 when they are
+    successful. This should be considered an EOF marker.</para>
+  </refsect1>
+
+  <refsect1>
+    <title>Notes</title>
+
+    <para>The <function>sd_journal_next()</function>,
+    <function>sd_journal_previous()</function>,
+    <function>sd_journal_next_skip()</function> and
+    <function>sd_journal_previous_skip()</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>Iterating through 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[]) {
-        int r;
-        sd_journal *j;
-        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;
-        }
-        SD_JOURNAL_FOREACH(j) {
-                const char *d;
-                size_t l;
-
-                r = sd_journal_get_data(j, "MESSAGE", &amp;d, &amp;l);
-                if (r &lt; 0) {
-                        fprintf(stderr, "Failed to read message field: %s\n", strerror(-r));
-                        continue;
-                }
-
-                printf("%.*s\n", (int) l, d);
-        }
-        sd_journal_close(j);
-        return 0;
+  int r;
+  sd_journal *j;
+  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;
+  }
+  SD_JOURNAL_FOREACH(j) {
+    const char *d;
+    size_t l;
+
+    r = sd_journal_get_data(j, "MESSAGE", (const void **)&amp;d, &amp;l);
+    if (r &lt; 0) {
+      fprintf(stderr, "Failed to read message field: %s\n", strerror(-r));
+      continue;
+    }
+
+    printf("%.*s\n", (int) l, 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>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>
-                </para>
-        </refsect1>
+    <para>
+      <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</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_get_realtime_usec</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+      <citerefentry><refentrytitle>sd_journal_get_cursor</refentrytitle><manvolnum>3</manvolnum></citerefentry>
+    </para>
+  </refsect1>
 
 </refentry>