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 83577620cbcb97719e0db5fee881a5ca8ae8f831..5b10b38b2bbd67e00b2fd65ee70712d54241b901 100644 (file)
--- a/man/sd_journal_next.xml
+++ b/man/sd_journal_next.xml
@@ -1,27 +1,13 @@
 <?xml version='1.0'?> <!--*-nxml-*-->
-<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
   "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
-
-<!--
-  SPDX-License-Identifier: LGPL-2.1+
-
-  Copyright 2012 Lennart Poettering
--->
+<!-- SPDX-License-Identifier: LGPL-2.1-or-later -->
 
 <refentry id="sd_journal_next" xmlns:xi="http://www.w3.org/2001/XInclude">
 
   <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>
@@ -32,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>
@@ -53,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>
@@ -91,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.</para>
+    <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³¹-1).</para>
 
     <para>The journal is strictly ordered by reception time, and hence
     advancing to the next entry guarantees that the entry then
@@ -133,8 +136,7 @@
   <refsect1>
     <title>Notes</title>
 
-    <para>All functions listed here are thread-agnostic and only a single thread may operate
-    on a given <structname>sd_journal</structname> object.</para>
+    <xi:include href="threads-aware.xml" xpointer="strict"/>
 
     <xi:include href="libsystemd-pkgconfig.xml" xpointer="pkgconfig-text"/>
   </refsect1>
@@ -144,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>