1<?xml version='1.0'?> <!--*-nxml-*--> 2<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" 3 "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> 4<!-- SPDX-License-Identifier: LGPL-2.1-or-later --> 5 6<refentry id="sd_journal_next" xmlns:xi="http://www.w3.org/2001/XInclude"> 7 8 <refentryinfo> 9 <title>sd_journal_next</title> 10 <productname>systemd</productname> 11 </refentryinfo> 12 13 <refmeta> 14 <refentrytitle>sd_journal_next</refentrytitle> 15 <manvolnum>3</manvolnum> 16 </refmeta> 17 18 <refnamediv> 19 <refname>sd_journal_next</refname> 20 <refname>sd_journal_previous</refname> 21 <refname>sd_journal_next_skip</refname> 22 <refname>sd_journal_previous_skip</refname> 23 <refname>SD_JOURNAL_FOREACH</refname> 24 <refname>SD_JOURNAL_FOREACH_BACKWARDS</refname> 25 <refpurpose>Advance or set back the read pointer in the journal</refpurpose> 26 </refnamediv> 27 28 <refsynopsisdiv> 29 <funcsynopsis> 30 <funcsynopsisinfo>#include <systemd/sd-journal.h></funcsynopsisinfo> 31 32 <funcprototype> 33 <funcdef>int <function>sd_journal_next</function></funcdef> 34 <paramdef>sd_journal *<parameter>j</parameter></paramdef> 35 </funcprototype> 36 37 <funcprototype> 38 <funcdef>int <function>sd_journal_previous</function></funcdef> 39 <paramdef>sd_journal *<parameter>j</parameter></paramdef> 40 </funcprototype> 41 42 <funcprototype> 43 <funcdef>int <function>sd_journal_next_skip</function></funcdef> 44 <paramdef>sd_journal *<parameter>j</parameter></paramdef> 45 <paramdef>uint64_t <parameter>skip</parameter></paramdef> 46 </funcprototype> 47 48 <funcprototype> 49 <funcdef>int <function>sd_journal_previous_skip</function></funcdef> 50 <paramdef>sd_journal *<parameter>j</parameter></paramdef> 51 <paramdef>uint64_t <parameter>skip</parameter></paramdef> 52 </funcprototype> 53 54 <funcprototype> 55 <funcdef><function>SD_JOURNAL_FOREACH</function></funcdef> 56 <paramdef>sd_journal *<parameter>j</parameter></paramdef> 57 </funcprototype> 58 59 <funcprototype> 60 <funcdef><function>SD_JOURNAL_FOREACH_BACKWARDS</function></funcdef> 61 <paramdef>sd_journal *<parameter>j</parameter></paramdef> 62 </funcprototype> 63 </funcsynopsis> 64 </refsynopsisdiv> 65 66 <refsect1> 67 <title>Description</title> 68 69 <para><function>sd_journal_next()</function> advances the read 70 pointer into the journal by one entry. The only argument taken is 71 a journal context object as allocated via 72 <citerefentry><refentrytitle>sd_journal_open</refentrytitle><manvolnum>3</manvolnum></citerefentry>. 73 After successful invocation the entry may be read with functions 74 such as 75 <citerefentry><refentrytitle>sd_journal_get_data</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para> 76 77 <para>Similarly, <function>sd_journal_previous()</function> sets 78 the read pointer back one entry.</para> 79 80 <para><function>sd_journal_next_skip()</function> and 81 <function>sd_journal_previous_skip()</function> advance/set back the read pointer by multiple 82 entries at once, as specified in the <varname>skip</varname> parameter. The <varname>skip</varname> 83 parameter must be less than or equal to 2147483647 (2³¹-1).</para> 84 85 <para>The journal is strictly ordered by reception time, and hence 86 advancing to the next entry guarantees that the entry then 87 pointing to is later in time than then previous one, or has the 88 same timestamp.</para> 89 90 <para>Note that 91 <citerefentry><refentrytitle>sd_journal_get_data</refentrytitle><manvolnum>3</manvolnum></citerefentry> 92 and related calls will fail unless 93 <function>sd_journal_next()</function> has been invoked at least 94 once in order to position the read pointer on a journal 95 entry.</para> 96 97 <para>Note that the <function>SD_JOURNAL_FOREACH()</function> 98 macro may be used as a wrapper around 99 <citerefentry><refentrytitle>sd_journal_seek_head</refentrytitle><manvolnum>3</manvolnum></citerefentry> 100 and <function>sd_journal_next()</function> in order to make 101 iterating through the journal easier. See below for an example. 102 Similarly, <function>SD_JOURNAL_FOREACH_BACKWARDS()</function> may 103 be used for iterating the journal in reverse order.</para> 104 </refsect1> 105 106 <refsect1> 107 <title>Return Value</title> 108 109 <para>The four calls return the number of entries advanced/set 110 back on success or a negative errno-style error code. When the end 111 or beginning of the journal is reached, a number smaller than 112 requested is returned. More specifically, if 113 <function>sd_journal_next()</function> or 114 <function>sd_journal_previous()</function> reach the end/beginning 115 of the journal they will return 0, instead of 1 when they are 116 successful. This should be considered an EOF marker.</para> 117 </refsect1> 118 119 <refsect1> 120 <title>Notes</title> 121 122 <xi:include href="threads-aware.xml" xpointer="strict"/> 123 124 <xi:include href="libsystemd-pkgconfig.xml" xpointer="pkgconfig-text"/> 125 </refsect1> 126 127 <refsect1> 128 <title>Examples</title> 129 130 <para>Iterating through the journal:</para> 131 132 <programlisting>#include <stdio.h> 133#include <string.h> 134#include <systemd/sd-journal.h> 135 136int main(int argc, char *argv[]) { 137 int r; 138 sd_journal *j; 139 r = sd_journal_open(&j, SD_JOURNAL_LOCAL_ONLY); 140 if (r < 0) { 141 fprintf(stderr, "Failed to open journal: %s\n", strerror(-r)); 142 return 1; 143 } 144 SD_JOURNAL_FOREACH(j) { 145 const char *d; 146 size_t l; 147 148 r = sd_journal_get_data(j, "MESSAGE", (const void **)&d, &l); 149 if (r < 0) { 150 fprintf(stderr, "Failed to read message field: %s\n", strerror(-r)); 151 continue; 152 } 153 154 printf("%.*s\n", (int) l, d); 155 } 156 sd_journal_close(j); 157 return 0; 158}</programlisting> 159 160 </refsect1> 161 162 <refsect1> 163 <title>See Also</title> 164 165 <para> 166 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, 167 <citerefentry><refentrytitle>sd-journal</refentrytitle><manvolnum>3</manvolnum></citerefentry>, 168 <citerefentry><refentrytitle>sd_journal_open</refentrytitle><manvolnum>3</manvolnum></citerefentry>, 169 <citerefentry><refentrytitle>sd_journal_get_data</refentrytitle><manvolnum>3</manvolnum></citerefentry>, 170 <citerefentry><refentrytitle>sd_journal_get_realtime_usec</refentrytitle><manvolnum>3</manvolnum></citerefentry>, 171 <citerefentry><refentrytitle>sd_journal_get_cursor</refentrytitle><manvolnum>3</manvolnum></citerefentry> 172 </para> 173 </refsect1> 174 175</refentry> 176