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