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>Similarly, <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. Similarly,
 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 a shared library, which can be compiled and
 160                 linked to with the
 161                 <constant>libsystemd</constant> <citerefentry project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 162                 file.</para>
 163         </refsect1>
 164
 165         <refsect1>
 166                 <title>Examples</title>
 167
 168                 <para>Iterating through the journal:</para>
 169
 170                 <programlisting>#include &lt;stdio.h&gt;
 171 #include &lt;string.h&gt;
 172 #include &lt;systemd/sd-journal.h&gt;
 173
 174 int main(int argc, char *argv[]) {
 175         int r;
 176         sd_journal *j;
 177         r = sd_journal_open(&amp;j, SD_JOURNAL_LOCAL_ONLY);
 178         if (r &lt; 0) {
 179                 fprintf(stderr, "Failed to open journal: %s\n", strerror(-r));
 180                 return 1;
 181         }
 182         SD_JOURNAL_FOREACH(j) {
 183                 const char *d;
 184                 size_t l;
 185
 186                 r = sd_journal_get_data(j, "MESSAGE", (const void **)&amp;d, &amp;l);
 187                 if (r &lt; 0) {
 188                         fprintf(stderr, "Failed to read message field: %s\n", strerror(-r));
 189                         continue;
 190                 }
 191
 192                 printf("%.*s\n", (int) l, d);
 193         }
 194         sd_journal_close(j);
 195         return 0;
 196 }</programlisting>
 197
 198         </refsect1>
 199
 200         <refsect1>
 201                 <title>See Also</title>
 202
 203                 <para>
 204                         <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 205                         <citerefentry><refentrytitle>sd-journal</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 206                         <citerefentry><refentrytitle>sd_journal_open</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 207                         <citerefentry><refentrytitle>sd_journal_get_data</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 208                         <citerefentry><refentrytitle>sd_journal_get_realtime_usec</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 209                         <citerefentry><refentrytitle>sd_journal_get_cursor</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 210                 </para>
 211         </refsect1>
 212
 213 </refentry>