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">
6 This file is part of systemd.
8 Copyright 2012 Lennart Poettering
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.
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.
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/>.
24 <refentry id="sd_journal_next">
27 <title>sd_journal_next</title>
28 <productname>systemd</productname>
32 <contrib>Developer</contrib>
33 <firstname>Lennart</firstname>
34 <surname>Poettering</surname>
35 <email>lennart@poettering.net</email>
41 <refentrytitle>sd_journal_next</refentrytitle>
42 <manvolnum>3</manvolnum>
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>
55 <funcsynopsisinfo>#include <systemd/sd-journal.h></funcsynopsisinfo>
58 <funcdef>int <function>sd_journal_next</function></funcdef>
59 <paramdef>sd_journal* <parameter>j</parameter></paramdef>
63 <funcdef>int <function>sd_journal_previous</function></funcdef>
64 <paramdef>sd_journal* <parameter>j</parameter></paramdef>
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>
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>
83 <title>Description</title>
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
89 <citerefentry><refentrytitle>sd_journal_open</refentrytitle><manvolnum>3</manvolnum></citerefentry>. After
90 successful invocation the entry may be read with
92 <citerefentry><refentrytitle>sd_journal_get_data</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para>
94 <para>Similar, <function>sd_journal_previous()</function> sets
95 the read pointer back one entry.</para>
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>
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>
109 <function>SD_JOURNAL_FOREACH()</function> macro may be used
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
121 <title>Return Value</title>
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>
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
143 <literal>libsystemd-journal</literal>
144 <citerefentry><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry>
149 <title>Examples</title>
151 <para>Iterating through the journal:</para>
153 <programlisting>#include <stdio.h>
154 #include <string.h>
155 #include <systemd/sd-journal.h>
157 int main(int argc, char *argv[]) {
160 r = sd_journal_open(&j, SD_JOURNAL_LOCAL_ONLY);
162 fprintf(stderr, "Failed to open journal: %s\n", strerror(-r));
165 SD_JOURNAL_FOREACH(j) {
169 r = sd_journal_get_data(j, "MESSAGE", &d, &l);
171 fprintf(stderr, "Failed to read message field: %s\n", strerror(-r));
175 printf("%.*s\n", (int) l, d);
184 <title>See Also</title>
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>