<refnamediv>
<refname>sd_journal_next</refname>
<refname>sd_journal_previous</refname>
+ <refname>sd_journal_step_one</refname>
<refname>sd_journal_next_skip</refname>
<refname>sd_journal_previous_skip</refname>
<refname>SD_JOURNAL_FOREACH</refname>
<paramdef>sd_journal *<parameter>j</parameter></paramdef>
</funcprototype>
+ <funcprototype>
+ <funcdef>int <function>sd_journal_step_one</function></funcdef>
+ <paramdef>sd_journal *<parameter>j</parameter></paramdef>
+ <paramdef>int <parameter>advanced</parameter></paramdef>
+ </funcprototype>
+
<funcprototype>
<funcdef>int <function>sd_journal_next_skip</function></funcdef>
<paramdef>sd_journal *<parameter>j</parameter></paramdef>
<para>Similarly, <function>sd_journal_previous()</function> sets
the read pointer back one entry.</para>
+ <para><function>sd_journal_step_one()</function> also moves the read pointer. If the current location
+ is the head of the journal, e.g. when this is called following
+ <function>sd_journal_seek_head()</function>, then this is equivalent to
+ <function>sd_journal_next()</function>, and the argument <varname>advanced</varname> will be ignored.
+ Similarly, if the current location is the tail of the journal, e.g. when this is called following
+ <function>sd_journal_seek_tail()</function>, then this is equivalent to
+ <function>sd_journal_previous()</function>, and <varname>advanced</varname> will be ignored. Otherwise,
+ this is equivalent to <function>sd_journal_next()</function> when <varname>advanced</varname> is
+ non-zero, and <function>sd_journal_previous()</function> when <varname>advanced</varname> is zero.</para>
+
<para><function>sd_journal_next_skip()</function> and
<function>sd_journal_previous_skip()</function> advance/set back the read pointer by multiple
entries at once, as specified in the <varname>skip</varname> parameter. The <varname>skip</varname>
- parameter must be less than or equal to 2147483647 (2^31-1).</para>
+ parameter must be less than or equal to 2147483647 (2³¹-1).</para>
<para>The journal is strictly ordered by reception time, and hence
advancing to the next entry guarantees that the entry then
<para>Iterating through the journal:</para>
- <programlisting>#include <stdio.h>
-#include <string.h>
-#include <systemd/sd-journal.h>
-
-int main(int argc, char *argv[]) {
- int r;
- sd_journal *j;
- r = sd_journal_open(&j, SD_JOURNAL_LOCAL_ONLY);
- if (r < 0) {
- fprintf(stderr, "Failed to open journal: %s\n", strerror(-r));
- return 1;
- }
- SD_JOURNAL_FOREACH(j) {
- const char *d;
- size_t l;
-
- r = sd_journal_get_data(j, "MESSAGE", (const void **)&d, &l);
- if (r < 0) {
- fprintf(stderr, "Failed to read message field: %s\n", strerror(-r));
- continue;
- }
-
- printf("%.*s\n", (int) l, d);
- }
- sd_journal_close(j);
- return 0;
-}</programlisting>
-
+ <programlisting><xi:include href="journal-iterate-foreach.c" parse="text" /></programlisting>
</refsect1>
<refsect1>