sd_journal_next.xml revision 67c3cf4f9ea35c1f789526b24a4d052d071902c0
67c3cf4f9ea35c1f789526b24a4d052d071902c0Lennart Poettering<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
67c3cf4f9ea35c1f789526b24a4d052d071902c0Lennart Poettering "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
67c3cf4f9ea35c1f789526b24a4d052d071902c0Lennart Poettering This file is part of systemd.
67c3cf4f9ea35c1f789526b24a4d052d071902c0Lennart Poettering Copyright 2012 Lennart Poettering
67c3cf4f9ea35c1f789526b24a4d052d071902c0Lennart Poettering systemd is free software; you can redistribute it and/or modify it
67c3cf4f9ea35c1f789526b24a4d052d071902c0Lennart Poettering under the terms of the GNU Lesser General Public License as published by
67c3cf4f9ea35c1f789526b24a4d052d071902c0Lennart Poettering the Free Software Foundation; either version 2.1 of the License, or
67c3cf4f9ea35c1f789526b24a4d052d071902c0Lennart Poettering (at your option) any later version.
67c3cf4f9ea35c1f789526b24a4d052d071902c0Lennart Poettering systemd is distributed in the hope that it will be useful, but
67c3cf4f9ea35c1f789526b24a4d052d071902c0Lennart Poettering WITHOUT ANY WARRANTY; without even the implied warranty of
67c3cf4f9ea35c1f789526b24a4d052d071902c0Lennart Poettering MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
67c3cf4f9ea35c1f789526b24a4d052d071902c0Lennart Poettering Lesser General Public License for more details.
67c3cf4f9ea35c1f789526b24a4d052d071902c0Lennart Poettering You should have received a copy of the GNU Lesser General Public License
67c3cf4f9ea35c1f789526b24a4d052d071902c0Lennart Poettering along with systemd; If not, see <http://www.gnu.org/licenses/>.
67c3cf4f9ea35c1f789526b24a4d052d071902c0Lennart Poettering <refentryinfo>
67c3cf4f9ea35c1f789526b24a4d052d071902c0Lennart Poettering </authorgroup>
67c3cf4f9ea35c1f789526b24a4d052d071902c0Lennart Poettering </refentryinfo>
67c3cf4f9ea35c1f789526b24a4d052d071902c0Lennart Poettering <refentrytitle>sd_journal_next</refentrytitle>
67c3cf4f9ea35c1f789526b24a4d052d071902c0Lennart Poettering <refname>sd_journal_previous_skip</refname>
67c3cf4f9ea35c1f789526b24a4d052d071902c0Lennart Poettering <refpurpose>Advance or set back the read pointer in the journal</refpurpose>
67c3cf4f9ea35c1f789526b24a4d052d071902c0Lennart Poettering <refsynopsisdiv>
67c3cf4f9ea35c1f789526b24a4d052d071902c0Lennart Poettering <funcsynopsis>
67c3cf4f9ea35c1f789526b24a4d052d071902c0Lennart Poettering <funcsynopsisinfo>#include <systemd/sd-journal.h></funcsynopsisinfo>
67c3cf4f9ea35c1f789526b24a4d052d071902c0Lennart Poettering <funcprototype>
67c3cf4f9ea35c1f789526b24a4d052d071902c0Lennart Poettering <funcdef>int <function>sd_journal_next</function></funcdef>
67c3cf4f9ea35c1f789526b24a4d052d071902c0Lennart Poettering <paramdef>sd_journal* <parameter>j</parameter></paramdef>
67c3cf4f9ea35c1f789526b24a4d052d071902c0Lennart Poettering </funcprototype>
67c3cf4f9ea35c1f789526b24a4d052d071902c0Lennart Poettering <funcprototype>
67c3cf4f9ea35c1f789526b24a4d052d071902c0Lennart Poettering <funcdef>int <function>sd_journal_previous</function></funcdef>
67c3cf4f9ea35c1f789526b24a4d052d071902c0Lennart Poettering <paramdef>sd_journal* <parameter>j</parameter></paramdef>
67c3cf4f9ea35c1f789526b24a4d052d071902c0Lennart Poettering </funcprototype>
67c3cf4f9ea35c1f789526b24a4d052d071902c0Lennart Poettering <funcprototype>
67c3cf4f9ea35c1f789526b24a4d052d071902c0Lennart Poettering <funcdef>int <function>sd_journal_next_skip</function></funcdef>
67c3cf4f9ea35c1f789526b24a4d052d071902c0Lennart Poettering <paramdef>sd_journal* <parameter>j</parameter></paramdef>
67c3cf4f9ea35c1f789526b24a4d052d071902c0Lennart Poettering <paramdef>uint64_t <parameter>skip</parameter></paramdef>
67c3cf4f9ea35c1f789526b24a4d052d071902c0Lennart Poettering </funcprototype>
67c3cf4f9ea35c1f789526b24a4d052d071902c0Lennart Poettering <funcprototype>
67c3cf4f9ea35c1f789526b24a4d052d071902c0Lennart Poettering <funcdef>int <function>sd_journal_previous_skip</function></funcdef>
67c3cf4f9ea35c1f789526b24a4d052d071902c0Lennart Poettering <paramdef>sd_journal* <parameter>j</parameter></paramdef>
67c3cf4f9ea35c1f789526b24a4d052d071902c0Lennart Poettering <paramdef>uint64_t <parameter>skip</parameter></paramdef>
67c3cf4f9ea35c1f789526b24a4d052d071902c0Lennart Poettering </funcprototype>
67c3cf4f9ea35c1f789526b24a4d052d071902c0Lennart Poettering </funcsynopsis>
67c3cf4f9ea35c1f789526b24a4d052d071902c0Lennart Poettering </refsynopsisdiv>
67c3cf4f9ea35c1f789526b24a4d052d071902c0Lennart Poettering <para><function>sd_journal_next()</function> advances
67c3cf4f9ea35c1f789526b24a4d052d071902c0Lennart Poettering the read pointer into the journal by one entry. The
67c3cf4f9ea35c1f789526b24a4d052d071902c0Lennart Poettering only argument taken is a journal context object as
67c3cf4f9ea35c1f789526b24a4d052d071902c0Lennart Poettering <citerefentry><refentrytitle>sd_journal_open</refentrytitle><manvolnum>3</manvolnum></citerefentry>. After
67c3cf4f9ea35c1f789526b24a4d052d071902c0Lennart Poettering successful invocation the entry may be read with
67c3cf4f9ea35c1f789526b24a4d052d071902c0Lennart Poettering functions such as
67c3cf4f9ea35c1f789526b24a4d052d071902c0Lennart Poettering <citerefentry><refentrytitle>sd_journal_get_data</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para>
67c3cf4f9ea35c1f789526b24a4d052d071902c0Lennart Poettering <para>Similar, <function>sd_journal_previous()</function> sets
67c3cf4f9ea35c1f789526b24a4d052d071902c0Lennart Poettering the read pointer back one entry.</para>
67c3cf4f9ea35c1f789526b24a4d052d071902c0Lennart Poettering <para><function>sd_journal_next_skip()</function> and
67c3cf4f9ea35c1f789526b24a4d052d071902c0Lennart Poettering <function>sd_journal_previous_skip()</function>
67c3cf4f9ea35c1f789526b24a4d052d071902c0Lennart Poettering advance/set back the read pointer by multiple entries
67c3cf4f9ea35c1f789526b24a4d052d071902c0Lennart Poettering at once, as specified in the <varname>skip</varname>
67c3cf4f9ea35c1f789526b24a4d052d071902c0Lennart Poettering parameter.</para>
67c3cf4f9ea35c1f789526b24a4d052d071902c0Lennart Poettering <para>The journal is strictly ordered by reception
67c3cf4f9ea35c1f789526b24a4d052d071902c0Lennart Poettering time, and hence advancing to the next entry guarantees
67c3cf4f9ea35c1f789526b24a4d052d071902c0Lennart Poettering that the entry then pointing to is later in time than
67c3cf4f9ea35c1f789526b24a4d052d071902c0Lennart Poettering then previous one, or has the same timestamp.</para>
67c3cf4f9ea35c1f789526b24a4d052d071902c0Lennart Poettering <para>Note that the
67c3cf4f9ea35c1f789526b24a4d052d071902c0Lennart Poettering <function>SD_JOURNAL_FOREACH()</function> macro may be used
67c3cf4f9ea35c1f789526b24a4d052d071902c0Lennart Poettering as a wrapper around
67c3cf4f9ea35c1f789526b24a4d052d071902c0Lennart Poettering <citerefentry><refentrytitle>sd_journal_seek_head</refentrytitle><manvolnum>3</manvolnum></citerefentry>
67c3cf4f9ea35c1f789526b24a4d052d071902c0Lennart Poettering and <function>sd_journal_next()</function> in order to
67c3cf4f9ea35c1f789526b24a4d052d071902c0Lennart Poettering make iteratring through the journal easier. See below
67c3cf4f9ea35c1f789526b24a4d052d071902c0Lennart Poettering for an example. Similar,
67c3cf4f9ea35c1f789526b24a4d052d071902c0Lennart Poettering <function>SD_JOURNAL_FOREACH_BACKWARDS()</function>
67c3cf4f9ea35c1f789526b24a4d052d071902c0Lennart Poettering may be used for iterating the journal in reverse
67c3cf4f9ea35c1f789526b24a4d052d071902c0Lennart Poettering <para>The four calls return the number of entries
67c3cf4f9ea35c1f789526b24a4d052d071902c0Lennart Poettering advanced/set back on success or a negative errno-style
67c3cf4f9ea35c1f789526b24a4d052d071902c0Lennart Poettering error code. When the end (resp. beginning) of the journal
67c3cf4f9ea35c1f789526b24a4d052d071902c0Lennart Poettering is reached a number smaller than requested is
67c3cf4f9ea35c1f789526b24a4d052d071902c0Lennart Poettering returned. More specifically, if
67c3cf4f9ea35c1f789526b24a4d052d071902c0Lennart Poettering <function>sd_journal_next()</function> or
67c3cf4f9ea35c1f789526b24a4d052d071902c0Lennart Poettering <function>sd_journal_previous()</function> reach the
67c3cf4f9ea35c1f789526b24a4d052d071902c0Lennart Poettering end/beginning of the journal they will return 0,
67c3cf4f9ea35c1f789526b24a4d052d071902c0Lennart Poettering instead of 1 when they are successful. This should be
67c3cf4f9ea35c1f789526b24a4d052d071902c0Lennart Poettering considered an EOF marker.</para>
67c3cf4f9ea35c1f789526b24a4d052d071902c0Lennart Poettering <para>The <function>sd_journal_next()</function>, <function>sd_journal_previous()</function>,
67c3cf4f9ea35c1f789526b24a4d052d071902c0Lennart Poettering <function>sd_journal_next_skip()</function> and
67c3cf4f9ea35c1f789526b24a4d052d071902c0Lennart Poettering <function>sd_journal_previous_skip()</function> interfaces are
67c3cf4f9ea35c1f789526b24a4d052d071902c0Lennart Poettering available as shared library, which can be compiled and
67c3cf4f9ea35c1f789526b24a4d052d071902c0Lennart Poettering linked to with the
67c3cf4f9ea35c1f789526b24a4d052d071902c0Lennart Poettering <citerefentry><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry>
67c3cf4f9ea35c1f789526b24a4d052d071902c0Lennart Poettering <para>Iterating through the journal:</para>
67c3cf4f9ea35c1f789526b24a4d052d071902c0Lennart Poettering#include <string.h>
67c3cf4f9ea35c1f789526b24a4d052d071902c0Lennart Poetteringint main(int argc, char *argv[]) {
67c3cf4f9ea35c1f789526b24a4d052d071902c0Lennart Poettering sd_journal *j;
67c3cf4f9ea35c1f789526b24a4d052d071902c0Lennart Poettering r = sd_journal_open(&j, SD_JOURNAL_LOCAL_ONLY);
67c3cf4f9ea35c1f789526b24a4d052d071902c0Lennart Poettering if (r < 0) {
67c3cf4f9ea35c1f789526b24a4d052d071902c0Lennart Poettering fprintf(stderr, "Failed to open journal: %s\n", strerror(-r));
67c3cf4f9ea35c1f789526b24a4d052d071902c0Lennart Poettering SD_JOURNAL_FOREACH(j) {
67c3cf4f9ea35c1f789526b24a4d052d071902c0Lennart Poettering const char *d;
67c3cf4f9ea35c1f789526b24a4d052d071902c0Lennart Poettering r = sd_journal_get_data(j, "MESSAGE", &d, &l);
67c3cf4f9ea35c1f789526b24a4d052d071902c0Lennart Poettering if (r < 0) {
67c3cf4f9ea35c1f789526b24a4d052d071902c0Lennart Poettering fprintf(stderr, "Failed to read message field: %s\n", strerror(-r));
67c3cf4f9ea35c1f789526b24a4d052d071902c0Lennart Poettering printf("%.*s\n", (int) l, d);
67c3cf4f9ea35c1f789526b24a4d052d071902c0Lennart Poettering sd_journal_close(j);
67c3cf4f9ea35c1f789526b24a4d052d071902c0Lennart Poettering}</programlisting>
67c3cf4f9ea35c1f789526b24a4d052d071902c0Lennart Poettering <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
67c3cf4f9ea35c1f789526b24a4d052d071902c0Lennart Poettering <citerefentry><refentrytitle>sd-journal</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
67c3cf4f9ea35c1f789526b24a4d052d071902c0Lennart Poettering <citerefentry><refentrytitle>sd_journal_open</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
67c3cf4f9ea35c1f789526b24a4d052d071902c0Lennart Poettering <citerefentry><refentrytitle>sd_journal_get_data</refentrytitle><manvolnum>3</manvolnum></citerefentry>