man/sd_journal_next_skip.html

   1 <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.78.1"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><style>
   2     a.headerlink {
   3       color: #c60f0f;
   4       font-size: 0.8em;
   5       padding: 0 4px 0 4px;
   6       text-decoration: none;
   7       visibility: hidden;
   8     }
   9
  10     a.headerlink:hover {
  11       background-color: #c60f0f;
  12       color: white;
  13     }
  14
  15     h1:hover > a.headerlink, h2:hover > a.headerlink, h3:hover > a.headerlink, dt:hover > a.headerlink {
  16       visibility: visible;
  17     }
  18   </style><a href="index.html">Index </a>·
  19   <a href="systemd.directives.html">Directives </a>·
  20   <a href="../python-systemd/index.html">Python </a>·
  21   <a href="../libudev/index.html">libudev </a>·
  22   <a href="../libudev/index.html">gudev </a><span style="float:right">systemd 204</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 &lt;systemd/sd-journal.h&gt;</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="idm259772947248"></a><h2 id="Description">Description<a class="headerlink" title="Permalink to this headline" href="#Description">¶</a></h2><p><code class="function">sd_journal_next()</code> advances
  23                 the read pointer into the journal by one entry. The
  24                 only argument taken is a journal context object as
  25                 allocated via
  26                 <a href="sd_journal_open.html"><span class="citerefentry"><span class="refentrytitle">sd_journal_open</span>(3)</span></a>. After
  27                 successful invocation the entry may be read with
  28                 functions such as
  29                 <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
  30                 the read pointer back one entry.</p><p><code class="function">sd_journal_next_skip()</code> and
  31                 <code class="function">sd_journal_previous_skip()</code>
  32                 advance/set back the read pointer by multiple entries
  33                 at once, as specified in the <code class="varname">skip</code>
  34                 parameter.</p><p>The journal is strictly ordered by reception
  35                 time, and hence advancing to the next entry guarantees
  36                 that the entry then pointing to is later in time than
  37                 then previous one, or has the same timestamp.</p><p>Note that
  38                 <a href="sd_journal_get_data.html"><span class="citerefentry"><span class="refentrytitle">sd_journal_get_data</span>(3)</span></a>
  39                 and related calls will fail unless
  40                 <code class="function">sd_journal_next()</code> has been
  41                 invoked at least once in order to position the read
  42                 pointer on a journal entry.</p><p>Note that the
  43                 <code class="function">SD_JOURNAL_FOREACH()</code> macro may be used
  44                 as a wrapper around
  45                 <a href="sd_journal_seek_head.html"><span class="citerefentry"><span class="refentrytitle">sd_journal_seek_head</span>(3)</span></a>
  46                 and <code class="function">sd_journal_next()</code> in order to
  47                 make iterating through the journal easier. See below
  48                 for an example. Similar,
  49                 <code class="function">SD_JOURNAL_FOREACH_BACKWARDS()</code>
  50                 may be used for iterating the journal in reverse
  51                 order.</p></div><div class="refsect1"><a name="idm259772933856"></a><h2 id="Return Value">Return Value<a class="headerlink" title="Permalink to this headline" href="#Return%20Value">¶</a></h2><p>The four calls return the number of entries
  52                 advanced/set back on success or a negative errno-style
  53                 error code. When the end or beginning of the journal
  54                 is reached, a number smaller than requested is
  55                 returned. More specifically, if
  56                 <code class="function">sd_journal_next()</code> or
  57                 <code class="function">sd_journal_previous()</code> reach the
  58                 end/beginning of the journal they will return 0,
  59                 instead of 1 when they are successful. This should be
  60                 considered an EOF marker.</p></div><div class="refsect1"><a name="idm259772923184"></a><h2 id="Notes">Notes<a class="headerlink" title="Permalink to this headline" href="#Notes">¶</a></h2><p>The <code class="function">sd_journal_next()</code>, <code class="function">sd_journal_previous()</code>,
  61                 <code class="function">sd_journal_next_skip()</code> and
  62                 <code class="function">sd_journal_previous_skip()</code> interfaces are
  63                 available as shared library, which can be compiled and
  64                 linked to with the
  65                 <code class="literal">libsystemd-journal</code>
  66                 <a href="pkg-config.html"><span class="citerefentry"><span class="refentrytitle">pkg-config</span>(1)</span></a>
  67                 file.</p></div><div class="refsect1"><a name="idm259772917408"></a><h2 id="Examples">Examples<a class="headerlink" title="Permalink to this headline" href="#Examples">¶</a></h2><p>Iterating through the journal:</p><pre class="programlisting">#include &lt;stdio.h&gt;
  68 #include &lt;string.h&gt;
  69 #include &lt;systemd/sd-journal.h&gt;
  70
  71 int main(int argc, char *argv[]) {
  72         int r;
  73         sd_journal *j;
  74         r = sd_journal_open(&amp;j, SD_JOURNAL_LOCAL_ONLY);
  75         if (r &lt; 0) {
  76                 fprintf(stderr, "Failed to open journal: %s\n", strerror(-r));
  77                 return 1;
  78         }
  79         SD_JOURNAL_FOREACH(j) {
  80                 const char *d;
  81                 size_t l;
  82
  83                 r = sd_journal_get_data(j, "MESSAGE", &amp;d, &amp;l);
  84                 if (r &lt; 0) {
  85                         fprintf(stderr, "Failed to read message field: %s\n", strerror(-r));
  86                         continue;
  87                 }
  88
  89                 printf("%.*s\n", (int) l, d);
  90         }
  91         sd_journal_close(j);
  92         return 0;
  93 }</pre></div><div class="refsect1"><a name="idm259772914160"></a><h2 id="See Also">See Also<a class="headerlink" title="Permalink to this headline" href="#See%20Also">¶</a></h2><p>
  94                         <a href="systemd.html"><span class="citerefentry"><span class="refentrytitle">systemd</span>(1)</span></a>,
  95                         <a href="sd-journal.html"><span class="citerefentry"><span class="refentrytitle">sd-journal</span>(3)</span></a>,
  96                         <a href="sd_journal_open.html"><span class="citerefentry"><span class="refentrytitle">sd_journal_open</span>(3)</span></a>,
  97                         <a href="sd_journal_get_data.html"><span class="citerefentry"><span class="refentrytitle">sd_journal_get_data</span>(3)</span></a>,
  98                         <a href="sd_journal_get_realtime_usec.html"><span class="citerefentry"><span class="refentrytitle">sd_journal_get_realtime_usec</span>(3)</span></a>,
  99                         <a href="sd_journal_get_cursor.html"><span class="citerefentry"><span class="refentrytitle">sd_journal_get_cursor</span>(3)</span></a>
 100                 </p></div></div></body></html>