tree-wide: fix a couple of typos

[thirdparty/systemd.git] / man / sd_journal_next.xml

diff --git a/man/sd_journal_next.xml b/man/sd_journal_next.xml
index 56083317371cd6d94c1d0478e17fc4a75296a3cf..5b10b38b2bbd67e00b2fd65ee70712d54241b901 100644 (file)
--- a/man/sd_journal_next.xml
+++ b/man/sd_journal_next.xml
@@ -18,6 +18,7 @@
   <refnamediv>
     <refname>sd_journal_next</refname>
     <refname>sd_journal_previous</refname>
+    <refname>sd_journal_step_one</refname>
     <refname>sd_journal_next_skip</refname>
     <refname>sd_journal_previous_skip</refname>
     <refname>SD_JOURNAL_FOREACH</refname>
@@ -39,6 +40,12 @@
         <paramdef>sd_journal *<parameter>j</parameter></paramdef>
       </funcprototype>
 
+      <funcprototype>
+        <funcdef>int <function>sd_journal_step_one</function></funcdef>
+        <paramdef>sd_journal *<parameter>j</parameter></paramdef>
+        <paramdef>int <parameter>advanced</parameter></paramdef>
+      </funcprototype>
+
       <funcprototype>
         <funcdef>int <function>sd_journal_next_skip</function></funcdef>
         <paramdef>sd_journal *<parameter>j</parameter></paramdef>
@@ -77,10 +84,20 @@
     <para>Similarly, <function>sd_journal_previous()</function> sets
     the read pointer back one entry.</para>
 
+    <para><function>sd_journal_step_one()</function> also moves the read pointer. If the current location
+    is the head of the journal, e.g. when this is called following
+    <function>sd_journal_seek_head()</function>, then this is equivalent to
+    <function>sd_journal_next()</function>, and the argument <varname>advanced</varname> will be ignored.
+    Similarly, if the current location is the tail of the journal, e.g. when this is called following
+    <function>sd_journal_seek_tail()</function>, then this is equivalent to
+    <function>sd_journal_previous()</function>, and <varname>advanced</varname> will be ignored. Otherwise,
+    this is equivalent to <function>sd_journal_next()</function> when <varname>advanced</varname> is
+    non-zero, and <function>sd_journal_previous()</function> when <varname>advanced</varname> is zero.</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. The <varname>skip</varname>
-    parameter must be less than or equal to 2147483647 (2^31-1).</para>
+    parameter must be less than or equal to 2147483647 (2³¹-1).</para>
 
     <para>The journal is strictly ordered by reception time, and hence
     advancing to the next entry guarantees that the entry then
@@ -129,34 +146,7 @@
 
     <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", (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>
-
+    <programlisting><xi:include href="journal-iterate-foreach.c" parse="text" /></programlisting>
   </refsect1>
 
   <refsect1>