man/sd_journal_next.xml

   1 <?xml version='1.0'?> <!--*-nxml-*-->
   2 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
   3   "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
   4 <!-- SPDX-License-Identifier: LGPL-2.1-or-later -->
   5
   6 <refentry id="sd_journal_next" xmlns:xi="http://www.w3.org/2001/XInclude">
   7
   8   <refentryinfo>
   9     <title>sd_journal_next</title>
  10     <productname>systemd</productname>
  11   </refentryinfo>
  12
  13   <refmeta>
  14     <refentrytitle>sd_journal_next</refentrytitle>
  15     <manvolnum>3</manvolnum>
  16   </refmeta>
  17
  18   <refnamediv>
  19     <refname>sd_journal_next</refname>
  20     <refname>sd_journal_previous</refname>
  21     <refname>sd_journal_step_one</refname>
  22     <refname>sd_journal_next_skip</refname>
  23     <refname>sd_journal_previous_skip</refname>
  24     <refname>SD_JOURNAL_FOREACH</refname>
  25     <refname>SD_JOURNAL_FOREACH_BACKWARDS</refname>
  26     <refpurpose>Advance or set back the read pointer in the journal</refpurpose>
  27   </refnamediv>
  28
  29   <refsynopsisdiv>
  30     <funcsynopsis>
  31       <funcsynopsisinfo>#include &lt;systemd/sd-journal.h&gt;</funcsynopsisinfo>
  32
  33       <funcprototype>
  34         <funcdef>int <function>sd_journal_next</function></funcdef>
  35         <paramdef>sd_journal *<parameter>j</parameter></paramdef>
  36       </funcprototype>
  37
  38       <funcprototype>
  39         <funcdef>int <function>sd_journal_previous</function></funcdef>
  40         <paramdef>sd_journal *<parameter>j</parameter></paramdef>
  41       </funcprototype>
  42
  43       <funcprototype>
  44         <funcdef>int <function>sd_journal_step_one</function></funcdef>
  45         <paramdef>sd_journal *<parameter>j</parameter></paramdef>
  46         <paramdef>int <parameter>advanced</parameter></paramdef>
  47       </funcprototype>
  48
  49       <funcprototype>
  50         <funcdef>int <function>sd_journal_next_skip</function></funcdef>
  51         <paramdef>sd_journal *<parameter>j</parameter></paramdef>
  52         <paramdef>uint64_t <parameter>skip</parameter></paramdef>
  53       </funcprototype>
  54
  55       <funcprototype>
  56         <funcdef>int <function>sd_journal_previous_skip</function></funcdef>
  57         <paramdef>sd_journal *<parameter>j</parameter></paramdef>
  58         <paramdef>uint64_t <parameter>skip</parameter></paramdef>
  59       </funcprototype>
  60
  61       <funcprototype>
  62         <funcdef><function>SD_JOURNAL_FOREACH</function></funcdef>
  63         <paramdef>sd_journal *<parameter>j</parameter></paramdef>
  64       </funcprototype>
  65
  66       <funcprototype>
  67         <funcdef><function>SD_JOURNAL_FOREACH_BACKWARDS</function></funcdef>
  68         <paramdef>sd_journal *<parameter>j</parameter></paramdef>
  69       </funcprototype>
  70     </funcsynopsis>
  71   </refsynopsisdiv>
  72
  73   <refsect1>
  74     <title>Description</title>
  75
  76     <para><function>sd_journal_next()</function> advances the read
  77     pointer into the journal by one entry. The only argument taken is
  78     a journal context object as allocated via
  79     <citerefentry><refentrytitle>sd_journal_open</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
  80     After successful invocation the entry may be read with functions
  81     such as
  82     <citerefentry><refentrytitle>sd_journal_get_data</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para>
  83
  84     <para>Similarly, <function>sd_journal_previous()</function> sets
  85     the read pointer back one entry.</para>
  86
  87     <para><function>sd_journal_step_one()</function> also moves the read pointer. If the current location
  88     is the head of the journal, e.g. when this is called following
  89     <function>sd_journal_seek_head()</function>, then this is equivalent to
  90     <function>sd_journal_next()</function>, and the argument <varname>advanced</varname> will be ignored.
  91     Similarly, if the current location is the tail of the journal, e.g. when this is called following
  92     <function>sd_journal_seek_tail()</function>, then this is equivalent to
  93     <function>sd_journal_previous()</function>, and <varname>advanced</varname> will be ignored. Otherwise,
  94     this is equivalent to <function>sd_journal_next()</function> when <varname>advanced</varname> is
  95     non-zero, and <function>sd_journal_previous()</function> when <varname>advanced</varname> is zero.</para>
  96
  97     <para><function>sd_journal_next_skip()</function> and
  98     <function>sd_journal_previous_skip()</function> advance/set back the read pointer by multiple
  99     entries at once, as specified in the <varname>skip</varname> parameter. The <varname>skip</varname>
 100     parameter must be less than or equal to 2147483647 (2³¹-1).</para>
 101
 102     <para>The journal is strictly ordered by reception time, and hence
 103     advancing to the next entry guarantees that the entry then
 104     pointing to is later in time than then previous one, or has the
 105     same timestamp.</para>
 106
 107     <para>Note that
 108     <citerefentry><refentrytitle>sd_journal_get_data</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 109     and related calls will fail unless
 110     <function>sd_journal_next()</function> has been invoked at least
 111     once in order to position the read pointer on a journal
 112     entry.</para>
 113
 114     <para>Note that the <function>SD_JOURNAL_FOREACH()</function>
 115     macro may be used as a wrapper around
 116     <citerefentry><refentrytitle>sd_journal_seek_head</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 117     and <function>sd_journal_next()</function> in order to make
 118     iterating through the journal easier. See below for an example.
 119     Similarly, <function>SD_JOURNAL_FOREACH_BACKWARDS()</function> may
 120     be used for iterating the journal in reverse order.</para>
 121   </refsect1>
 122
 123   <refsect1>
 124     <title>Return Value</title>
 125
 126     <para>The four calls return the number of entries advanced/set
 127     back on success or a negative errno-style error code. When the end
 128     or beginning of the journal is reached, a number smaller than
 129     requested is returned. More specifically, if
 130     <function>sd_journal_next()</function> or
 131     <function>sd_journal_previous()</function> reach the end/beginning
 132     of the journal they will return 0, instead of 1 when they are
 133     successful. This should be considered an EOF marker.</para>
 134   </refsect1>
 135
 136   <refsect1>
 137     <title>Notes</title>
 138
 139     <xi:include href="threads-aware.xml" xpointer="strict"/>
 140
 141     <xi:include href="libsystemd-pkgconfig.xml" xpointer="pkgconfig-text"/>
 142   </refsect1>
 143
 144   <refsect1>
 145     <title>Examples</title>
 146
 147     <para>Iterating through the journal:</para>
 148
 149     <programlisting><xi:include href="journal-iterate-foreach.c" parse="text" /></programlisting>
 150   </refsect1>
 151
 152   <refsect1>
 153     <title>History</title>
 154     <para><function>sd_journal_next()</function>,
 155     <function>sd_journal_previous()</function>,
 156     <function>sd_journal_next_skip()</function>,
 157     <function>sd_journal_previous_skip()</function>,
 158     <function>SD_JOURNAL_FOREACH()</function>, and
 159     <function>SD_JOURNAL_FOREACH_BACKWARDS()</function> were added in version 187.</para>
 160     <para><function>sd_journal_step_one()</function> was added in version 254.</para>
 161   </refsect1>
 162
 163   <refsect1>
 164     <title>See Also</title>
 165
 166     <para>
 167       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 168       <citerefentry><refentrytitle>sd-journal</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 169       <citerefentry><refentrytitle>sd_journal_open</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 170       <citerefentry><refentrytitle>sd_journal_get_data</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 171       <citerefentry><refentrytitle>sd_journal_get_realtime_usec</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 172       <citerefentry><refentrytitle>sd_journal_get_cursor</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 173     </para>
 174   </refsect1>
 175
 176 </refentry>