sd_journal_next.xml revision 494a66821815e8109afa136bd42818b85da38c09
ee93ea764a2b8189253e912c8447f9419033f6d4Francisc Nicolae Bungiu<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
e9458b1a7a19a63aa4c179f9ab20f4d50681c168Jens Elkner "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
ee93ea764a2b8189253e912c8447f9419033f6d4Francisc Nicolae Bungiu This file is part of systemd.
431571057e88a650a974adec93ea4bb5173b6213Felix Gabriel Mance Copyright 2012 Lennart Poettering
ee93ea764a2b8189253e912c8447f9419033f6d4Francisc Nicolae Bungiu systemd is free software; you can redistribute it and/or modify it
ee93ea764a2b8189253e912c8447f9419033f6d4Francisc Nicolae Bungiu under the terms of the GNU Lesser General Public License as published by
ee93ea764a2b8189253e912c8447f9419033f6d4Francisc Nicolae Bungiu the Free Software Foundation; either version 2.1 of the License, or
ee93ea764a2b8189253e912c8447f9419033f6d4Francisc Nicolae Bungiu (at your option) any later version.
19e01e1a7e319063434bd86c8ecbc5f241ef9993Felix Gabriel Mance systemd is distributed in the hope that it will be useful, but
ee93ea764a2b8189253e912c8447f9419033f6d4Francisc Nicolae Bungiu WITHOUT ANY WARRANTY; without even the implied warranty of
80875f917d741946a39d0ec0b5721e46ba609823Till Mossakowski MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
ee93ea764a2b8189253e912c8447f9419033f6d4Francisc Nicolae Bungiu Lesser General Public License for more details.
ee93ea764a2b8189253e912c8447f9419033f6d4Francisc Nicolae Bungiu You should have received a copy of the GNU Lesser General Public License
be2439588008221e691321fdf4f75432cfb72878Felix Gabriel Mance along with systemd; If not, see <http://www.gnu.org/licenses/>.
e0f1794e365dd347e97b37d7d22b2fce27296fa1Christian Maeder <authorgroup>
ee93ea764a2b8189253e912c8447f9419033f6d4Francisc Nicolae Bungiu </refentryinfo>
ee93ea764a2b8189253e912c8447f9419033f6d4Francisc Nicolae Bungiu <refentrytitle>sd_journal_next</refentrytitle>
ee93ea764a2b8189253e912c8447f9419033f6d4Francisc Nicolae Bungiu <refname>sd_journal_previous</refname>
ee93ea764a2b8189253e912c8447f9419033f6d4Francisc Nicolae Bungiu <refname>sd_journal_next_skip</refname>
ee93ea764a2b8189253e912c8447f9419033f6d4Francisc Nicolae Bungiu <refname>sd_journal_previous_skip</refname>
ee93ea764a2b8189253e912c8447f9419033f6d4Francisc Nicolae Bungiu <refname>SD_JOURNAL_FOREACH</refname>
ee93ea764a2b8189253e912c8447f9419033f6d4Francisc Nicolae Bungiu <refname>SD_JOURNAL_FOREACH_BACKWARDS</refname>
b84c87f199dc287d235d7dad6ea344f6912ef531Christian Maeder <refpurpose>Advance or set back the read pointer in the journal</refpurpose>
ee93ea764a2b8189253e912c8447f9419033f6d4Francisc Nicolae Bungiu <refsynopsisdiv>
be00381168b3f10192afabbba136fb06d3a9f358Christian Maeder <funcsynopsis>
be00381168b3f10192afabbba136fb06d3a9f358Christian Maeder <funcsynopsisinfo>#include <systemd/sd-journal.h></funcsynopsisinfo>
27fdf879983dd28e211b41f3be6c0e930b7c816bFelix Gabriel Mance <funcprototype>
7852de3551fc797566ee71165bafe05b6d81728cnotanartist <funcdef>int <function>sd_journal_next</function></funcdef>
ee93ea764a2b8189253e912c8447f9419033f6d4Francisc Nicolae Bungiu <paramdef>sd_journal* <parameter>j</parameter></paramdef>
27fdf879983dd28e211b41f3be6c0e930b7c816bFelix Gabriel Mance </funcprototype>
ee93ea764a2b8189253e912c8447f9419033f6d4Francisc Nicolae Bungiu <funcprototype>
27fdf879983dd28e211b41f3be6c0e930b7c816bFelix Gabriel Mance <funcdef>int <function>sd_journal_previous</function></funcdef>
d0f58d27c2536eba454d8f77de8617bc6a2c99cdFelix Gabriel Mance <paramdef>sd_journal* <parameter>j</parameter></paramdef>
d0f58d27c2536eba454d8f77de8617bc6a2c99cdFelix Gabriel Mance </funcprototype>
d0f58d27c2536eba454d8f77de8617bc6a2c99cdFelix Gabriel Mance <funcprototype>
431571057e88a650a974adec93ea4bb5173b6213Felix Gabriel Mance <funcdef>int <function>sd_journal_next_skip</function></funcdef>
ee93ea764a2b8189253e912c8447f9419033f6d4Francisc Nicolae Bungiu <paramdef>sd_journal* <parameter>j</parameter></paramdef>
27fdf879983dd28e211b41f3be6c0e930b7c816bFelix Gabriel Mance <paramdef>uint64_t <parameter>skip</parameter></paramdef>
424860079d47bf490fa98d5d7498096a0447c569mcodescu </funcprototype>
60f30f0eeeacdfc1e0dfe39664373ddf5a0675adFelix Gabriel Mance <funcprototype>
0dd6e7830de0887c9a12356447975a826b3b3db2Christian Maeder <funcdef>int <function>sd_journal_previous_skip</function></funcdef>
424860079d47bf490fa98d5d7498096a0447c569mcodescu <paramdef>sd_journal* <parameter>j</parameter></paramdef>
424860079d47bf490fa98d5d7498096a0447c569mcodescu <paramdef>uint64_t <parameter>skip</parameter></paramdef>
424860079d47bf490fa98d5d7498096a0447c569mcodescu </funcprototype>
d6d81ead61a5f9fb7d047e623f7898e730c258camcodescu <funcprototype>
ee93ea764a2b8189253e912c8447f9419033f6d4Francisc Nicolae Bungiu <funcdef><function>SD_JOURNAL_FOREACH</function></funcdef>
ee93ea764a2b8189253e912c8447f9419033f6d4Francisc Nicolae Bungiu <paramdef>sd_journal* <parameter>j</parameter></paramdef>
ee93ea764a2b8189253e912c8447f9419033f6d4Francisc Nicolae Bungiu </funcprototype>
7852de3551fc797566ee71165bafe05b6d81728cnotanartist <funcprototype>
ee93ea764a2b8189253e912c8447f9419033f6d4Francisc Nicolae Bungiu <funcdef><function>SD_JOURNAL_FOREACH_BACKWARDS</function></funcdef>
60f30f0eeeacdfc1e0dfe39664373ddf5a0675adFelix Gabriel Mance <paramdef>sd_journal* <parameter>j</parameter></paramdef>
9475501a6acf48434052d9e6f4a05ed6681eaaabFrancisc Nicolae Bungiu </funcprototype>
ee93ea764a2b8189253e912c8447f9419033f6d4Francisc Nicolae Bungiu </funcsynopsis>
7852de3551fc797566ee71165bafe05b6d81728cnotanartist </refsynopsisdiv>
0dd6e7830de0887c9a12356447975a826b3b3db2Christian Maeder <para><function>sd_journal_next()</function> advances
424860079d47bf490fa98d5d7498096a0447c569mcodescu the read pointer into the journal by one entry. The
0dd6e7830de0887c9a12356447975a826b3b3db2Christian Maeder only argument taken is a journal context object as
0dd6e7830de0887c9a12356447975a826b3b3db2Christian Maeder allocated via
ee93ea764a2b8189253e912c8447f9419033f6d4Francisc Nicolae Bungiu <citerefentry><refentrytitle>sd_journal_open</refentrytitle><manvolnum>3</manvolnum></citerefentry>. After
ee93ea764a2b8189253e912c8447f9419033f6d4Francisc Nicolae Bungiu successful invocation the entry may be read with
d0f58d27c2536eba454d8f77de8617bc6a2c99cdFelix Gabriel Mance functions such as
60f30f0eeeacdfc1e0dfe39664373ddf5a0675adFelix Gabriel Mance <citerefentry><refentrytitle>sd_journal_get_data</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para>
ee93ea764a2b8189253e912c8447f9419033f6d4Francisc Nicolae Bungiu <para>Similarly, <function>sd_journal_previous()</function> sets
ee93ea764a2b8189253e912c8447f9419033f6d4Francisc Nicolae Bungiu the read pointer back one entry.</para>
ee93ea764a2b8189253e912c8447f9419033f6d4Francisc Nicolae Bungiu <para><function>sd_journal_next_skip()</function> and
ee93ea764a2b8189253e912c8447f9419033f6d4Francisc Nicolae Bungiu <function>sd_journal_previous_skip()</function>
ee93ea764a2b8189253e912c8447f9419033f6d4Francisc Nicolae Bungiu advance/set back the read pointer by multiple entries
ee93ea764a2b8189253e912c8447f9419033f6d4Francisc Nicolae Bungiu at once, as specified in the <varname>skip</varname>
ee93ea764a2b8189253e912c8447f9419033f6d4Francisc Nicolae Bungiu parameter.</para>
3d3889e0cefcdce9b3f43c53aaa201943ac2e895Jonathan von Schroeder <para>The journal is strictly ordered by reception
ee93ea764a2b8189253e912c8447f9419033f6d4Francisc Nicolae Bungiu time, and hence advancing to the next entry guarantees
3d3889e0cefcdce9b3f43c53aaa201943ac2e895Jonathan von Schroeder that the entry then pointing to is later in time than
3d3889e0cefcdce9b3f43c53aaa201943ac2e895Jonathan von Schroeder then previous one, or has the same timestamp.</para>
ee93ea764a2b8189253e912c8447f9419033f6d4Francisc Nicolae Bungiu <para>Note that
ee93ea764a2b8189253e912c8447f9419033f6d4Francisc Nicolae Bungiu <citerefentry><refentrytitle>sd_journal_get_data</refentrytitle><manvolnum>3</manvolnum></citerefentry>
ee93ea764a2b8189253e912c8447f9419033f6d4Francisc Nicolae Bungiu and related calls will fail unless
3d3889e0cefcdce9b3f43c53aaa201943ac2e895Jonathan von Schroeder <function>sd_journal_next()</function> has been
ee93ea764a2b8189253e912c8447f9419033f6d4Francisc Nicolae Bungiu invoked at least once in order to position the read
31e9d2a02e15b7dbc157e0d3fb3b84f6c8666482Christian Maeder pointer on a journal entry.</para>
ee93ea764a2b8189253e912c8447f9419033f6d4Francisc Nicolae Bungiu <para>Note that the
656f17ae9b7610ff2de1b6eedeeadea0c3bcdc8dChristian Maeder <function>SD_JOURNAL_FOREACH()</function> macro may be used
d3cb3401882f6956de016f8eecbec1cd3b868acbFelix Gabriel Mance as a wrapper around
d3cb3401882f6956de016f8eecbec1cd3b868acbFelix Gabriel Mance <citerefentry><refentrytitle>sd_journal_seek_head</refentrytitle><manvolnum>3</manvolnum></citerefentry>
d3cb3401882f6956de016f8eecbec1cd3b868acbFelix Gabriel Mance and <function>sd_journal_next()</function> in order to
d3cb3401882f6956de016f8eecbec1cd3b868acbFelix Gabriel Mance make iterating through the journal easier. See below
ee93ea764a2b8189253e912c8447f9419033f6d4Francisc Nicolae Bungiu for an example. Similarly,
ee93ea764a2b8189253e912c8447f9419033f6d4Francisc Nicolae Bungiu <function>SD_JOURNAL_FOREACH_BACKWARDS()</function>
ee93ea764a2b8189253e912c8447f9419033f6d4Francisc Nicolae Bungiu may be used for iterating the journal in reverse
7852de3551fc797566ee71165bafe05b6d81728cnotanartist order.</para>
ee93ea764a2b8189253e912c8447f9419033f6d4Francisc Nicolae Bungiu <para>The four calls return the number of entries
0dd6e7830de0887c9a12356447975a826b3b3db2Christian Maeder advanced/set back on success or a negative errno-style
ee93ea764a2b8189253e912c8447f9419033f6d4Francisc Nicolae Bungiu error code. When the end or beginning of the journal
ee93ea764a2b8189253e912c8447f9419033f6d4Francisc Nicolae Bungiu is reached, a number smaller than requested is
ee93ea764a2b8189253e912c8447f9419033f6d4Francisc Nicolae Bungiu returned. More specifically, if
ee93ea764a2b8189253e912c8447f9419033f6d4Francisc Nicolae Bungiu <function>sd_journal_next()</function> or
ee93ea764a2b8189253e912c8447f9419033f6d4Francisc Nicolae Bungiu <function>sd_journal_previous()</function> reach the
ee93ea764a2b8189253e912c8447f9419033f6d4Francisc Nicolae Bungiu end/beginning of the journal they will return 0,
06acd8a23b2f06e7b2373d53f738cf56c7f03223Francisc Nicolae Bungiu instead of 1 when they are successful. This should be
ee93ea764a2b8189253e912c8447f9419033f6d4Francisc Nicolae Bungiu considered an EOF marker.</para>
32bbac77828be0233953f8fe476edb0a9585408dChristian Maeder <para>The <function>sd_journal_next()</function>, <function>sd_journal_previous()</function>,
80875f917d741946a39d0ec0b5721e46ba609823Till Mossakowski <function>sd_journal_next_skip()</function> and
80875f917d741946a39d0ec0b5721e46ba609823Till Mossakowski <function>sd_journal_previous_skip()</function> interfaces are
80875f917d741946a39d0ec0b5721e46ba609823Till Mossakowski available as a shared library, which can be compiled and
80875f917d741946a39d0ec0b5721e46ba609823Till Mossakowski linked to with the
32bbac77828be0233953f8fe476edb0a9585408dChristian Maeder <constant>libsystemd-journal</constant> <citerefentry><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry>
b84c87f199dc287d235d7dad6ea344f6912ef531Christian Maeder <para>Iterating through the journal:</para>
cf0439f74f1d55a9840d38a88f9b0f4fc00d5547Christian Maeder#include <string.h>
cf0439f74f1d55a9840d38a88f9b0f4fc00d5547Christian Maederint main(int argc, char *argv[]) {
cf0439f74f1d55a9840d38a88f9b0f4fc00d5547Christian Maeder sd_journal *j;
cf0439f74f1d55a9840d38a88f9b0f4fc00d5547Christian Maeder r = sd_journal_open(&j, SD_JOURNAL_LOCAL_ONLY);
cf0439f74f1d55a9840d38a88f9b0f4fc00d5547Christian Maeder if (r < 0) {
cf0439f74f1d55a9840d38a88f9b0f4fc00d5547Christian Maeder fprintf(stderr, "Failed to open journal: %s\n", strerror(-r));
ee93ea764a2b8189253e912c8447f9419033f6d4Francisc Nicolae Bungiu SD_JOURNAL_FOREACH(j) {
7852de3551fc797566ee71165bafe05b6d81728cnotanartist const char *d;
80875f917d741946a39d0ec0b5721e46ba609823Till Mossakowski r = sd_journal_get_data(j, "MESSAGE", &d, &l);
624f8c31bd8d6746b93f4b5966aa6fc7680fefc5Felix Gabriel Mance if (r < 0) {
80875f917d741946a39d0ec0b5721e46ba609823Till Mossakowski fprintf(stderr, "Failed to read message field: %s\n", strerror(-r));
ee93ea764a2b8189253e912c8447f9419033f6d4Francisc Nicolae Bungiu printf("%.*s\n", (int) l, d);
ee93ea764a2b8189253e912c8447f9419033f6d4Francisc Nicolae Bungiu sd_journal_close(j);
b84c87f199dc287d235d7dad6ea344f6912ef531Christian Maeder}</programlisting>
d0f58d27c2536eba454d8f77de8617bc6a2c99cdFelix Gabriel Mance <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
431571057e88a650a974adec93ea4bb5173b6213Felix Gabriel Mance <citerefentry><refentrytitle>sd-journal</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
431571057e88a650a974adec93ea4bb5173b6213Felix Gabriel Mance <citerefentry><refentrytitle>sd_journal_open</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
b90f0b7fd6ccfbdd7e5adb65b1f6c02c7758ff5cmcodescu <citerefentry><refentrytitle>sd_journal_get_data</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
b90f0b7fd6ccfbdd7e5adb65b1f6c02c7758ff5cmcodescu <citerefentry><refentrytitle>sd_journal_get_realtime_usec</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
b90f0b7fd6ccfbdd7e5adb65b1f6c02c7758ff5cmcodescu <citerefentry><refentrytitle>sd_journal_get_cursor</refentrytitle><manvolnum>3</manvolnum></citerefentry>
b90f0b7fd6ccfbdd7e5adb65b1f6c02c7758ff5cmcodescu </refsect1>