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