sd_journal_next.xml revision 798d3a524ea57aaf40cb53858aaa45ec702f012d
67c3cf4f9ea35c1f789526b24a4d052d071902c0Lennart Poettering<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek "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/>.
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <productname>systemd</productname>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <email>lennart@poettering.net</email>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <refentrytitle>sd_journal_next</refentrytitle>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <refname>sd_journal_next</refname>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <refname>sd_journal_previous</refname>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <refname>sd_journal_next_skip</refname>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <refname>sd_journal_previous_skip</refname>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <refname>SD_JOURNAL_FOREACH</refname>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <refname>SD_JOURNAL_FOREACH_BACKWARDS</refname>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <refpurpose>Advance or set back the read pointer in the journal</refpurpose>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <refsynopsisdiv>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <funcsynopsisinfo>#include <systemd/sd-journal.h></funcsynopsisinfo>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <funcdef>int <function>sd_journal_next</function></funcdef>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <paramdef>sd_journal *<parameter>j</parameter></paramdef>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek </funcprototype>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <funcdef>int <function>sd_journal_previous</function></funcdef>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <paramdef>sd_journal *<parameter>j</parameter></paramdef>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek </funcprototype>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <funcdef>int <function>sd_journal_next_skip</function></funcdef>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <paramdef>sd_journal *<parameter>j</parameter></paramdef>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <paramdef>uint64_t <parameter>skip</parameter></paramdef>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek </funcprototype>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <funcdef>int <function>sd_journal_previous_skip</function></funcdef>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <paramdef>sd_journal *<parameter>j</parameter></paramdef>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <paramdef>uint64_t <parameter>skip</parameter></paramdef>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek </funcprototype>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <funcdef><function>SD_JOURNAL_FOREACH</function></funcdef>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <paramdef>sd_journal *<parameter>j</parameter></paramdef>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek </funcprototype>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <funcdef><function>SD_JOURNAL_FOREACH_BACKWARDS</function></funcdef>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <paramdef>sd_journal *<parameter>j</parameter></paramdef>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek </funcprototype>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek </refsynopsisdiv>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <para><function>sd_journal_next()</function> advances the read
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek pointer into the journal by one entry. The only argument taken is
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek a journal context object as allocated via
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <citerefentry><refentrytitle>sd_journal_open</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek After successful invocation the entry may be read with functions
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <citerefentry><refentrytitle>sd_journal_get_data</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <para>Similarly, <function>sd_journal_previous()</function> sets
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek the read pointer back one entry.</para>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <para><function>sd_journal_next_skip()</function> and
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <function>sd_journal_previous_skip()</function> advance/set back
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek the read pointer by multiple entries at once, as specified in the
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <varname>skip</varname> parameter.</para>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <para>The journal is strictly ordered by reception time, and hence
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek advancing to the next entry guarantees that the entry then
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek pointing to is later in time than then previous one, or has the
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek same timestamp.</para>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <citerefentry><refentrytitle>sd_journal_get_data</refentrytitle><manvolnum>3</manvolnum></citerefentry>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek and related calls will fail unless
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <function>sd_journal_next()</function> has been invoked at least
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek once in order to position the read pointer on a journal
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <para>Note that the <function>SD_JOURNAL_FOREACH()</function>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek macro may be used as a wrapper around
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <citerefentry><refentrytitle>sd_journal_seek_head</refentrytitle><manvolnum>3</manvolnum></citerefentry>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek and <function>sd_journal_next()</function> in order to make
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek iterating through the journal easier. See below for an example.
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek Similarly, <function>SD_JOURNAL_FOREACH_BACKWARDS()</function> may
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek be used for iterating the journal in reverse order.</para>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <para>The four calls return the number of entries advanced/set
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek back on success or a negative errno-style error code. When the end
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek or beginning of the journal is reached, a number smaller than
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek requested is returned. More specifically, if
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <function>sd_journal_next()</function> or
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <function>sd_journal_previous()</function> reach the end/beginning
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek of the journal they will return 0, instead of 1 when they are
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek successful. This should be considered an EOF marker.</para>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <para>The <function>sd_journal_next()</function>,
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <function>sd_journal_previous()</function>,
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <function>sd_journal_next_skip()</function> and
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <function>sd_journal_previous_skip()</function> interfaces are
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek available as a shared library, which can be compiled and linked to
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <constant>libsystemd</constant> <citerefentry project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <para>Iterating through the journal:</para>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <programlisting>#include <stdio.h>
67c3cf4f9ea35c1f789526b24a4d052d071902c0Lennart Poettering#include <string.h>
67c3cf4f9ea35c1f789526b24a4d052d071902c0Lennart Poetteringint main(int argc, char *argv[]) {
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek r = sd_journal_open(&j, SD_JOURNAL_LOCAL_ONLY);
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek fprintf(stderr, "Failed to open journal: %s\n", strerror(-r));
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek SD_JOURNAL_FOREACH(j) {
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek r = sd_journal_get_data(j, "MESSAGE", (const void **)&d, &l);
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek fprintf(stderr, "Failed to read message field: %s\n", strerror(-r));
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek printf("%.*s\n", (int) l, d);
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek sd_journal_close(j);
67c3cf4f9ea35c1f789526b24a4d052d071902c0Lennart Poettering}</programlisting>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <citerefentry><refentrytitle>sd-journal</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <citerefentry><refentrytitle>sd_journal_open</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <citerefentry><refentrytitle>sd_journal_get_data</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <citerefentry><refentrytitle>sd_journal_get_realtime_usec</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <citerefentry><refentrytitle>sd_journal_get_cursor</refentrytitle><manvolnum>3</manvolnum></citerefentry>