man/sd_journal_test_cursor.html

   1 <html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>sd_journal_get_cursor</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 214</span><hr><div class="refentry"><a name="sd_journal_get_cursor"></a><div class="titlepage"></div><div class="refnamediv"><h2>Name</h2><p>sd_journal_get_cursor, sd_journal_test_cursor — Get cursor string for or test cursor string against the current journal entry</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_get_cursor</b>(</code></td><td>sd_journal *<var class="pdparam">j</var>, </td></tr><tr><td> </td><td>char **<var class="pdparam">cursor</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_test_cursor</b>(</code></td><td>sd_journal *<var class="pdparam">j</var>, </td></tr><tr><td> </td><td>const char *<var class="pdparam">cursor</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer"> </div></div></div><div class="refsect1"><a name="idm214192150240"></a><h2 id="Description">Description<a class="headerlink" title="Permalink to this headline" href="#Description">¶</a></h2><p><code class="function">sd_journal_get_cursor()</code>
  23                 returns a cursor string for the current journal
  24                 entry. A cursor is a serialization of the current
  25                 journal position formatted as text. The string only
  26                 contains printable characters and can be passed around
  27                 in text form. The cursor identifies a journal entry
  28                 globally and in a stable way and may be used to later
  29                 seek to it via
  30                 <a href="sd_journal_seek_cursor.html"><span class="citerefentry"><span class="refentrytitle">sd_journal_seek_cursor</span>(3)</span></a>. The
  31                 cursor string should be considered opaque and not be
  32                 parsed by clients. Seeking to a cursor position
  33                 without the specific entry being available locally
  34                 will seek to the next closest (in terms of time)
  35                 available entry. The call takes two arguments: a
  36                 journal context object and a pointer to a string
  37                 pointer where the cursor string will be placed. The
  38                 string is allocated via libc
  39                 <a href="malloc.html"><span class="citerefentry"><span class="refentrytitle">malloc</span>(3)</span></a>
  40                 and should be freed after use with
  41                 <a href="free.html"><span class="citerefentry"><span class="refentrytitle">free</span>(3)</span></a>.</p><p>Note that
  42                 <code class="function">sd_journal_get_cursor()</code> will not
  43                 work before
  44                 <a href="sd_journal_next.html"><span class="citerefentry"><span class="refentrytitle">sd_journal_next</span>(3)</span></a>
  45                 (or related call) has been called at least once, in
  46                 order to position the read pointer at a valid
  47                 entry.</p><p><code class="function">sd_journal_test_cursor()</code>
  48                 may be used to check whether the current position in
  49                 the journal matches the specified cursor. This is
  50                 useful since cursor strings do not uniquely identify
  51                 an entry: the same entry might be referred to by
  52                 multiple different cursor strings, and hence string
  53                 comparing cursors is not possible. Use this call to
  54                 verify after an invocation of
  55                 <a href="sd_journal_seek_cursor.html"><span class="citerefentry"><span class="refentrytitle">sd_journal_seek_cursor</span>(3)</span></a>
  56                 whether the entry being sought to was actually found
  57                 in the journal or the next closest entry was used
  58                 instead.</p></div><div class="refsect1"><a name="idm214192215984"></a><h2 id="Return Value">Return Value<a class="headerlink" title="Permalink to this headline" href="#Return%20Value">¶</a></h2><p><code class="function">sd_journal_get_cursor()</code>
  59                 returns 0 on success or a negative errno-style error
  60                 code. <code class="function">sd_journal_test_cursor()</code>
  61                 returns positive if the current entry matches the
  62                 specified cursor, 0 if it does not match the specified
  63                 cursor or a negative errno-style error code on
  64                 failure.</p></div><div class="refsect1"><a name="idm214192213184"></a><h2 id="Notes">Notes<a class="headerlink" title="Permalink to this headline" href="#Notes">¶</a></h2><p>The <code class="function">sd_journal_get_cursor()</code>
  65                 and <code class="function">sd_journal_test_cursor()</code>
  66                 interfaces are available as a shared library, which can
  67                 be compiled and linked to with the
  68                 <code class="constant">libsystemd</code> <a href="pkg-config.html"><span class="citerefentry"><span class="refentrytitle">pkg-config</span>(1)</span></a>
  69                 file.</p></div><div class="refsect1"><a name="idm214192209056"></a><h2 id="See Also">See Also<a class="headerlink" title="Permalink to this headline" href="#See%20Also">¶</a></h2><p>
  70                         <a href="systemd.html"><span class="citerefentry"><span class="refentrytitle">systemd</span>(1)</span></a>,
  71                         <a href="sd-journal.html"><span class="citerefentry"><span class="refentrytitle">sd-journal</span>(3)</span></a>,
  72                         <a href="sd_journal_open.html"><span class="citerefentry"><span class="refentrytitle">sd_journal_open</span>(3)</span></a>,
  73                         <a href="sd_journal_seek_cursor.html"><span class="citerefentry"><span class="refentrytitle">sd_journal_seek_cursor</span>(3)</span></a>
  74                 </p></div></div></body></html>