man/sd_journal_next.xml

   1 <?xml version='1.0'?> <!--*-nxml-*-->
   2 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
   3   "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
   4
   5 <!--
   6   SPDX-License-Identifier: LGPL-2.1+
   7 -->
   8
   9 <refentry id="sd_journal_next" xmlns:xi="http://www.w3.org/2001/XInclude">
  10
  11   <refentryinfo>
  12     <title>sd_journal_next</title>
  13     <productname>systemd</productname>
  14
  15     <authorgroup>
  16       <author>
  17         <contrib>Developer</contrib>
  18         <firstname>Lennart</firstname>
  19         <surname>Poettering</surname>
  20         <email>lennart@poettering.net</email>
  21       </author>
  22     </authorgroup>
  23   </refentryinfo>
  24
  25   <refmeta>
  26     <refentrytitle>sd_journal_next</refentrytitle>
  27     <manvolnum>3</manvolnum>
  28   </refmeta>
  29
  30   <refnamediv>
  31     <refname>sd_journal_next</refname>
  32     <refname>sd_journal_previous</refname>
  33     <refname>sd_journal_next_skip</refname>
  34     <refname>sd_journal_previous_skip</refname>
  35     <refname>SD_JOURNAL_FOREACH</refname>
  36     <refname>SD_JOURNAL_FOREACH_BACKWARDS</refname>
  37     <refpurpose>Advance or set back the read pointer in the journal</refpurpose>
  38   </refnamediv>
  39
  40   <refsynopsisdiv>
  41     <funcsynopsis>
  42       <funcsynopsisinfo>#include &lt;systemd/sd-journal.h&gt;</funcsynopsisinfo>
  43
  44       <funcprototype>
  45         <funcdef>int <function>sd_journal_next</function></funcdef>
  46         <paramdef>sd_journal *<parameter>j</parameter></paramdef>
  47       </funcprototype>
  48
  49       <funcprototype>
  50         <funcdef>int <function>sd_journal_previous</function></funcdef>
  51         <paramdef>sd_journal *<parameter>j</parameter></paramdef>
  52       </funcprototype>
  53
  54       <funcprototype>
  55         <funcdef>int <function>sd_journal_next_skip</function></funcdef>
  56         <paramdef>sd_journal *<parameter>j</parameter></paramdef>
  57         <paramdef>uint64_t <parameter>skip</parameter></paramdef>
  58       </funcprototype>
  59
  60       <funcprototype>
  61         <funcdef>int <function>sd_journal_previous_skip</function></funcdef>
  62         <paramdef>sd_journal *<parameter>j</parameter></paramdef>
  63         <paramdef>uint64_t <parameter>skip</parameter></paramdef>
  64       </funcprototype>
  65
  66       <funcprototype>
  67         <funcdef><function>SD_JOURNAL_FOREACH</function></funcdef>
  68         <paramdef>sd_journal *<parameter>j</parameter></paramdef>
  69       </funcprototype>
  70
  71       <funcprototype>
  72         <funcdef><function>SD_JOURNAL_FOREACH_BACKWARDS</function></funcdef>
  73         <paramdef>sd_journal *<parameter>j</parameter></paramdef>
  74       </funcprototype>
  75     </funcsynopsis>
  76   </refsynopsisdiv>
  77
  78   <refsect1>
  79     <title>Description</title>
  80
  81     <para><function>sd_journal_next()</function> advances the read
  82     pointer into the journal by one entry. The only argument taken is
  83     a journal context object as allocated via
  84     <citerefentry><refentrytitle>sd_journal_open</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
  85     After successful invocation the entry may be read with functions
  86     such as
  87     <citerefentry><refentrytitle>sd_journal_get_data</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para>
  88
  89     <para>Similarly, <function>sd_journal_previous()</function> sets
  90     the read pointer back one entry.</para>
  91
  92     <para><function>sd_journal_next_skip()</function> and
  93     <function>sd_journal_previous_skip()</function> advance/set back
  94     the read pointer by multiple entries at once, as specified in the
  95     <varname>skip</varname> parameter.</para>
  96
  97     <para>The journal is strictly ordered by reception time, and hence
  98     advancing to the next entry guarantees that the entry then
  99     pointing to is later in time than then previous one, or has the
 100     same timestamp.</para>
 101
 102     <para>Note that
 103     <citerefentry><refentrytitle>sd_journal_get_data</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 104     and related calls will fail unless
 105     <function>sd_journal_next()</function> has been invoked at least
 106     once in order to position the read pointer on a journal
 107     entry.</para>
 108
 109     <para>Note that the <function>SD_JOURNAL_FOREACH()</function>
 110     macro may be used as a wrapper around
 111     <citerefentry><refentrytitle>sd_journal_seek_head</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 112     and <function>sd_journal_next()</function> in order to make
 113     iterating through the journal easier. See below for an example.
 114     Similarly, <function>SD_JOURNAL_FOREACH_BACKWARDS()</function> may
 115     be used for iterating the journal in reverse order.</para>
 116   </refsect1>
 117
 118   <refsect1>
 119     <title>Return Value</title>
 120
 121     <para>The four calls return the number of entries advanced/set
 122     back on success or a negative errno-style error code. When the end
 123     or beginning of the journal is reached, a number smaller than
 124     requested is returned. More specifically, if
 125     <function>sd_journal_next()</function> or
 126     <function>sd_journal_previous()</function> reach the end/beginning
 127     of the journal they will return 0, instead of 1 when they are
 128     successful. This should be considered an EOF marker.</para>
 129   </refsect1>
 130
 131   <refsect1>
 132     <title>Notes</title>
 133
 134     <para>All functions listed here are thread-agnostic and only a single thread may operate
 135     on a given <structname>sd_journal</structname> object.</para>
 136
 137     <xi:include href="libsystemd-pkgconfig.xml" xpointer="pkgconfig-text"/>
 138   </refsect1>
 139
 140   <refsect1>
 141     <title>Examples</title>
 142
 143     <para>Iterating through the journal:</para>
 144
 145     <programlisting>#include &lt;stdio.h&gt;
 146 #include &lt;string.h&gt;
 147 #include &lt;systemd/sd-journal.h&gt;
 148
 149 int main(int argc, char *argv[]) {
 150   int r;
 151   sd_journal *j;
 152   r = sd_journal_open(&amp;j, SD_JOURNAL_LOCAL_ONLY);
 153   if (r &lt; 0) {
 154     fprintf(stderr, "Failed to open journal: %s\n", strerror(-r));
 155     return 1;
 156   }
 157   SD_JOURNAL_FOREACH(j) {
 158     const char *d;
 159     size_t l;
 160
 161     r = sd_journal_get_data(j, "MESSAGE", (const void **)&amp;d, &amp;l);
 162     if (r &lt; 0) {
 163       fprintf(stderr, "Failed to read message field: %s\n", strerror(-r));
 164       continue;
 165     }
 166
 167     printf("%.*s\n", (int) l, d);
 168   }
 169   sd_journal_close(j);
 170   return 0;
 171 }</programlisting>
 172
 173   </refsect1>
 174
 175   <refsect1>
 176     <title>See Also</title>
 177
 178     <para>
 179       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 180       <citerefentry><refentrytitle>sd-journal</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 181       <citerefentry><refentrytitle>sd_journal_open</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 182       <citerefentry><refentrytitle>sd_journal_get_data</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 183       <citerefentry><refentrytitle>sd_journal_get_realtime_usec</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 184       <citerefentry><refentrytitle>sd_journal_get_cursor</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 185     </para>
 186   </refsect1>
 187
 188 </refentry>