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 219</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="idm139955963395968"></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> returns a
  23     cursor string for the current journal entry. A cursor is a
  24     serialization of the current journal position formatted as text.
  25     The string only contains printable characters and can be passed
  26     around in text form. The cursor identifies a journal entry
  27     globally and in a stable way and may be used to later seek to it
  28     via
  29     <a href="sd_journal_seek_cursor.html"><span class="citerefentry"><span class="refentrytitle">sd_journal_seek_cursor</span>(3)</span></a>.
  30     The cursor string should be considered opaque and not be parsed by
  31     clients. Seeking to a cursor position without the specific entry
  32     being available locally will seek to the next closest (in terms of
  33     time) available entry. The call takes two arguments: a journal
  34     context object and a pointer to a string pointer where the cursor
  35     string will be placed. The string is allocated via libc
  36     <a href="malloc.html"><span class="citerefentry"><span class="refentrytitle">malloc</span>(3)</span></a>
  37     and should be freed after use with
  38     <a href="http://man7.org/linux/man-pages/man3/free.3.html"><span class="citerefentry"><span class="refentrytitle">free</span>(3)</span></a>.</p><p>Note that <code class="function">sd_journal_get_cursor()</code> will
  39     not work before
  40     <a href="sd_journal_next.html"><span class="citerefentry"><span class="refentrytitle">sd_journal_next</span>(3)</span></a>
  41     (or related call) has been called at least once, in order to
  42     position the read pointer at a valid entry.</p><p><code class="function">sd_journal_test_cursor()</code>
  43     may be used to check whether the current position in
  44     the journal matches the specified cursor. This is
  45     useful since cursor strings do not uniquely identify
  46     an entry: the same entry might be referred to by
  47     multiple different cursor strings, and hence string
  48     comparing cursors is not possible. Use this call to
  49     verify after an invocation of
  50     <a href="sd_journal_seek_cursor.html"><span class="citerefentry"><span class="refentrytitle">sd_journal_seek_cursor</span>(3)</span></a>
  51     whether the entry being sought to was actually found
  52     in the journal or the next closest entry was used
  53     instead.</p></div><div class="refsect1"><a name="idm139955967288928"></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> returns 0 on
  54     success or a negative errno-style error code.
  55     <code class="function">sd_journal_test_cursor()</code> returns positive if
  56     the current entry matches the specified cursor, 0 if it does not
  57     match the specified cursor or a negative errno-style error code on
  58     failure.</p></div><div class="refsect1"><a name="idm139955967286400"></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> and
  59     <code class="function">sd_journal_test_cursor()</code> interfaces are
  60     available as a shared library, which can be compiled and linked to
  61     with the
  62     <code class="constant">libsystemd</code> <a href="http://linux.die.net/man/1/pkg-config"><span class="citerefentry"><span class="refentrytitle">pkg-config</span>(1)</span></a>
  63     file.</p></div><div class="refsect1"><a name="idm139955967282032"></a><h2 id="See Also">See Also<a class="headerlink" title="Permalink to this headline" href="#See%20Also">¶</a></h2><p>
  64       <a href="systemd.html"><span class="citerefentry"><span class="refentrytitle">systemd</span>(1)</span></a>,
  65       <a href="sd-journal.html"><span class="citerefentry"><span class="refentrytitle">sd-journal</span>(3)</span></a>,
  66       <a href="sd_journal_open.html"><span class="citerefentry"><span class="refentrytitle">sd_journal_open</span>(3)</span></a>,
  67       <a href="sd_journal_seek_cursor.html"><span class="citerefentry"><span class="refentrytitle">sd_journal_seek_cursor</span>(3)</span></a>
  68     </p></div></div></body></html>