~ubuntu-branches/ubuntu/trusty/systemd/trusty

<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>sd_journal_next</title><meta name="generator" content="DocBook XSL Stylesheets V1.77.1"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><a href="index.html">Index </a>·

<a href="systemd.directives.html">Directives </a>·

<a href="../python-systemd/index.html">Python </a>·

<a href="../libudev/index.html">libudev </a>·

<a href="../libudev/index.html">gudev </a><span style="float:right">systemd 202</span><hr><div class="refentry"><a name="sd_journal_next"></a><div class="titlepage"></div><div class="refnamediv"><h2>Name</h2><p>sd_journal_next, sd_journal_previous, sd_journal_next_skip, sd_journal_previous_skip, SD_JOURNAL_FOREACH, SD_JOURNAL_FOREACH_BACKWARDS — Advance or set back the read pointer in the journal</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><div class="funcsynopsis"><pre class="funcsynopsisinfo">#include <systemd/sd-journal.h></pre><table border="0" class="funcprototype-table" summary="Function synopsis" style="cellspacing: 0; cellpadding: 0;"><tr><td><code class="funcdef">int <b class="fsfunc">sd_journal_next</b>(</code></td><td>sd_journal* <var class="pdparam">j</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer"> </div><table border="0" class="funcprototype-table" summary="Function synopsis" style="cellspacing: 0; cellpadding: 0;"><tr><td><code class="funcdef">int <b class="fsfunc">sd_journal_previous</b>(</code></td><td>sd_journal* <var class="pdparam">j</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer"> </div><table border="0" class="funcprototype-table" summary="Function synopsis" style="cellspacing: 0; cellpadding: 0;"><tr><td><code class="funcdef">int <b class="fsfunc">sd_journal_next_skip</b>(</code></td><td>sd_journal* <var class="pdparam">j</var>, </td></tr><tr><td> </td><td>uint64_t <var class="pdparam">skip</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer"> </div><table border="0" class="funcprototype-table" summary="Function synopsis" style="cellspacing: 0; cellpadding: 0;"><tr><td><code class="funcdef">int <b class="fsfunc">sd_journal_previous_skip</b>(</code></td><td>sd_journal* <var class="pdparam">j</var>, </td></tr><tr><td> </td><td>uint64_t <var class="pdparam">skip</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer"> </div><table border="0" class="funcprototype-table" summary="Function synopsis" style="cellspacing: 0; cellpadding: 0;"><tr><td><code class="funcdef"><b class="fsfunc">SD_JOURNAL_FOREACH</b>(</code></td><td>sd_journal* <var class="pdparam">j</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer"> </div><table border="0" class="funcprototype-table" summary="Function synopsis" style="cellspacing: 0; cellpadding: 0;"><tr><td><code class="funcdef"><b class="fsfunc">SD_JOURNAL_FOREACH_BACKWARDS</b>(</code></td><td>sd_journal* <var class="pdparam">j</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer"> </div></div></div><div class="refsect1"><a name="idp26192"></a><h2>Description</h2><p><code class="function">sd_journal_next()</code> advances

the read pointer into the journal by one entry. The

only argument taken is a journal context object as

allocated via

<a href="sd_journal_open.html"><span class="citerefentry"><span class="refentrytitle">sd_journal_open</span>(3)</span></a>. After

successful invocation the entry may be read with

functions such as

<a href="sd_journal_get_data.html"><span class="citerefentry"><span class="refentrytitle">sd_journal_get_data</span>(3)</span></a>.</p><p>Similar, <code class="function">sd_journal_previous()</code> sets

the read pointer back one entry.</p><p><code class="function">sd_journal_next_skip()</code> and

<code class="function">sd_journal_previous_skip()</code>

advance/set back the read pointer by multiple entries

at once, as specified in the <code class="varname">skip</code>

parameter.</p><p>The journal is strictly ordered by reception

time, and hence advancing to the next entry guarantees

that the entry then pointing to is later in time than

then previous one, or has the same timestamp.</p><p>Note that

<a href="sd_journal_get_data.html"><span class="citerefentry"><span class="refentrytitle">sd_journal_get_data</span>(3)</span></a>

and related calls will fail unless

<code class="function">sd_journal_next()</code> has been

invoked at least once in order to position the read

pointer on a journal entry.</p><p>Note that the

<code class="function">SD_JOURNAL_FOREACH()</code> macro may be used

as a wrapper around

<a href="sd_journal_seek_head.html"><span class="citerefentry"><span class="refentrytitle">sd_journal_seek_head</span>(3)</span></a>

and <code class="function">sd_journal_next()</code> in order to

make iterating through the journal easier. See below

for an example. Similar,

<code class="function">SD_JOURNAL_FOREACH_BACKWARDS()</code>

may be used for iterating the journal in reverse

order.</p></div><div class="refsect1"><a name="idp39584"></a><h2>Return Value</h2><p>The four calls return the number of entries

advanced/set back on success or a negative errno-style

error code. When the end or beginning of the journal

is reached, a number smaller than requested is

returned. More specifically, if

<code class="function">sd_journal_next()</code> or

<code class="function">sd_journal_previous()</code> reach the

end/beginning of the journal they will return 0,

instead of 1 when they are successful. This should be

considered an EOF marker.</p></div><div class="refsect1"><a name="idp49696"></a><h2>Notes</h2><p>The <code class="function">sd_journal_next()</code>, <code class="function">sd_journal_previous()</code>,

<code class="function">sd_journal_next_skip()</code> and

<code class="function">sd_journal_previous_skip()</code> interfaces are

available as shared library, which can be compiled and

linked to with the

<code class="literal">libsystemd-journal</code>

<a href="pkg-config.html"><span class="citerefentry"><span class="refentrytitle">pkg-config</span>(1)</span></a>

file.</p></div><div class="refsect1"><a name="idp55520"></a><h2>Examples</h2><p>Iterating through the journal:</p><pre class="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", &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;

}</pre></div><div class="refsect1"><a name="idp59024"></a><h2>See Also</h2><p>

<a href="systemd.html"><span class="citerefentry"><span class="refentrytitle">systemd</span>(1)</span></a>,

<a href="sd-journal.html"><span class="citerefentry"><span class="refentrytitle">sd-journal</span>(3)</span></a>,

<a href="sd_journal_open.html"><span class="citerefentry"><span class="refentrytitle">sd_journal_open</span>(3)</span></a>,

<a href="sd_journal_get_data.html"><span class="citerefentry"><span class="refentrytitle">sd_journal_get_data</span>(3)</span></a>,

<a href="sd_journal_get_realtime_usec.html"><span class="citerefentry"><span class="refentrytitle">sd_journal_get_realtime_usec</span>(3)</span></a>,

<a href="sd_journal_get_cursor.html"><span class="citerefentry"><span class="refentrytitle">sd_journal_get_cursor</span>(3)</span></a>

</p></div></div></body></html>

Older »