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