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                 <refname>SD_JOURNAL_FOREACH</refname>
  51                 <refname>SD_JOURNAL_FOREACH_BACKWARDS</refname>
  52                 <refpurpose>Advance or set back the read pointer in the journal</refpurpose>
  53         </refnamediv>
  54
  55         <refsynopsisdiv>
  56                 <funcsynopsis>
  57                         <funcsynopsisinfo>#include &lt;systemd/sd-journal.h&gt;</funcsynopsisinfo>
  58
  59                         <funcprototype>
  60                                 <funcdef>int <function>sd_journal_next</function></funcdef>
  61                                 <paramdef>sd_journal* <parameter>j</parameter></paramdef>
  62                         </funcprototype>
  63
  64                         <funcprototype>
  65                                 <funcdef>int <function>sd_journal_previous</function></funcdef>
  66                                 <paramdef>sd_journal* <parameter>j</parameter></paramdef>
  67                         </funcprototype>
  68
  69                         <funcprototype>
  70                                 <funcdef>int <function>sd_journal_next_skip</function></funcdef>
  71                                 <paramdef>sd_journal* <parameter>j</parameter></paramdef>
  72                                 <paramdef>uint64_t <parameter>skip</parameter></paramdef>
  73                         </funcprototype>
  74
  75                         <funcprototype>
  76                                 <funcdef>int <function>sd_journal_previous_skip</function></funcdef>
  77                                 <paramdef>sd_journal* <parameter>j</parameter></paramdef>
  78                                 <paramdef>uint64_t <parameter>skip</parameter></paramdef>
  79                         </funcprototype>
  80
  81                         <funcprototype>
  82                                 <funcdef><function>SD_JOURNAL_FOREACH</function></funcdef>
  83                                 <paramdef>sd_journal* <parameter>j</parameter></paramdef>
  84                         </funcprototype>
  85
  86                         <funcprototype>
  87                                 <funcdef><function>SD_JOURNAL_FOREACH_BACKWARDS</function></funcdef>
  88                                 <paramdef>sd_journal* <parameter>j</parameter></paramdef>
  89                         </funcprototype>
  90                 </funcsynopsis>
  91         </refsynopsisdiv>
  92
  93         <refsect1>
  94                 <title>Description</title>
  95
  96                 <para><function>sd_journal_next()</function> advances
  97                 the read pointer into the journal by one entry. The
  98                 only argument taken is a journal context object as
  99                 allocated via
 100                 <citerefentry><refentrytitle>sd_journal_open</refentrytitle><manvolnum>3</manvolnum></citerefentry>. After
 101                 successful invocation the entry may be read with
 102                 functions such as
 103                 <citerefentry><refentrytitle>sd_journal_get_data</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para>
 104
 105                 <para>Similar, <function>sd_journal_previous()</function> sets
 106                 the read pointer back one entry.</para>
 107
 108                 <para><function>sd_journal_next_skip()</function> and
 109                 <function>sd_journal_previous_skip()</function>
 110                 advance/set back the read pointer by multiple entries
 111                 at once, as specified in the <varname>skip</varname>
 112                 parameter.</para>
 113
 114                 <para>The journal is strictly ordered by reception
 115                 time, and hence advancing to the next entry guarantees
 116                 that the entry then pointing to is later in time than
 117                 then previous one, or has the 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
 123                 invoked at least once in order to position the read
 124                 pointer on a journal entry.</para>
 125
 126                 <para>Note that the
 127                 <function>SD_JOURNAL_FOREACH()</function> macro may be used
 128                 as a wrapper around
 129                 <citerefentry><refentrytitle>sd_journal_seek_head</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 130                 and <function>sd_journal_next()</function> in order to
 131                 make iterating through the journal easier. See below
 132                 for an example. Similar,
 133                 <function>SD_JOURNAL_FOREACH_BACKWARDS()</function>
 134                 may be used for iterating the journal in reverse
 135                 order.</para>
 136         </refsect1>
 137
 138         <refsect1>
 139                 <title>Return Value</title>
 140
 141                 <para>The four calls return the number of entries
 142                 advanced/set back on success or a negative errno-style
 143                 error code. When the end or beginning of the journal
 144                 is reached, a number smaller than requested is
 145                 returned. More specifically, if
 146                 <function>sd_journal_next()</function> or
 147                 <function>sd_journal_previous()</function> reach the
 148                 end/beginning of the journal they will return 0,
 149                 instead of 1 when they are successful. This should be
 150                 considered an EOF marker.</para>
 151         </refsect1>
 152
 153         <refsect1>
 154                 <title>Notes</title>
 155
 156                 <para>The <function>sd_journal_next()</function>, <function>sd_journal_previous()</function>,
 157                 <function>sd_journal_next_skip()</function> and
 158                 <function>sd_journal_previous_skip()</function> interfaces are
 159                 available as shared library, which can be compiled and
 160                 linked to with the
 161                 <literal>libsystemd-journal</literal>
 162                 <citerefentry><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 163                 file.</para>
 164         </refsect1>
 165
 166         <refsect1>
 167                 <title>Examples</title>
 168
 169                 <para>Iterating through the journal:</para>
 170
 171                 <programlisting>#include &lt;stdio.h&gt;
 172 #include &lt;string.h&gt;
 173 #include &lt;systemd/sd-journal.h&gt;
 174
 175 int main(int argc, char *argv[]) {
 176         int r;
 177         sd_journal *j;
 178         r = sd_journal_open(&amp;j, SD_JOURNAL_LOCAL_ONLY);
 179         if (r &lt; 0) {
 180                 fprintf(stderr, "Failed to open journal: %s\n", strerror(-r));
 181                 return 1;
 182         }
 183         SD_JOURNAL_FOREACH(j) {
 184                 const char *d;
 185                 size_t l;
 186
 187                 r = sd_journal_get_data(j, "MESSAGE", &amp;d, &amp;l);
 188                 if (r &lt; 0) {
 189                         fprintf(stderr, "Failed to read message field: %s\n", strerror(-r));
 190                         continue;
 191                 }
 192
 193                 printf("%.*s\n", (int) l, d);
 194         }
 195         sd_journal_close(j);
 196         return 0;
 197 }</programlisting>
 198
 199         </refsect1>
 200
 201         <refsect1>
 202                 <title>See Also</title>
 203
 204                 <para>
 205                         <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 206                         <citerefentry><refentrytitle>sd-journal</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 207                         <citerefentry><refentrytitle>sd_journal_open</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 208                         <citerefentry><refentrytitle>sd_journal_get_data</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 209                         <citerefentry><refentrytitle>sd_journal_get_realtime_usec</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 210                         <citerefentry><refentrytitle>sd_journal_get_cursor</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 211                 </para>
 212         </refsect1>
 213
 214 </refentry>