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 <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>
57 <funcsynopsisinfo>#include
<systemd/sd-journal.h
></funcsynopsisinfo>
60 <funcdef>int
<function>sd_journal_next
</function></funcdef>
61 <paramdef>sd_journal*
<parameter>j
</parameter></paramdef>
65 <funcdef>int
<function>sd_journal_previous
</function></funcdef>
66 <paramdef>sd_journal*
<parameter>j
</parameter></paramdef>
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>
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>
82 <funcdef><function>SD_JOURNAL_FOREACH
</function></funcdef>
83 <paramdef>sd_journal*
<parameter>j
</parameter></paramdef>
87 <funcdef><function>SD_JOURNAL_FOREACH_BACKWARDS
</function></funcdef>
88 <paramdef>sd_journal*
<parameter>j
</parameter></paramdef>
94 <title>Description
</title>
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
100 <citerefentry><refentrytitle>sd_journal_open
</refentrytitle><manvolnum>3</manvolnum></citerefentry>. After
101 successful invocation the entry may be read with
103 <citerefentry><refentrytitle>sd_journal_get_data
</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
</para>
105 <para>Similar,
<function>sd_journal_previous()
</function> sets
106 the read pointer back one entry.
</para>
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>
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>
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>
127 <function>SD_JOURNAL_FOREACH()
</function> macro may be used
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
139 <title>Return Value
</title>
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>
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
161 <literal>libsystemd-journal
</literal>
162 <citerefentry><refentrytitle>pkg-config
</refentrytitle><manvolnum>1</manvolnum></citerefentry>
167 <title>Examples
</title>
169 <para>Iterating through the journal:
</para>
171 <programlisting>#include
<stdio.h
>
172 #include
<string.h
>
173 #include
<systemd/sd-journal.h
>
175 int main(int argc, char *argv[]) {
178 r = sd_journal_open(
&j, SD_JOURNAL_LOCAL_ONLY);
180 fprintf(stderr,
"Failed to open journal: %s\n", strerror(-r));
183 SD_JOURNAL_FOREACH(j) {
187 r = sd_journal_get_data(j,
"MESSAGE",
&d,
&l);
189 fprintf(stderr,
"Failed to read message field: %s\n", strerror(-r));
193 printf(
"%.*s\n", (int) l, d);
202 <title>See Also
</title>
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>