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