X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?p=elogind.git;a=blobdiff_plain;f=man%2Fsd_journal_get_cursor.xml;h=4cee7d5b636069791d2d4a44ec18de86d35fa29c;hp=9e00ef7c82f28b5b1255cda321df2a5e24d34658;hb=0a244b8ecb6dfcb381fe831dc2aa9bacb2c12975;hpb=4a010f4e6e95964d7acaa33be768dbdb5e46d72a

diff --git a/man/sd_journal_get_cursor.xml b/man/sd_journal_get_cursor.xml
index 9e00ef7c8..4cee7d5b6 100644
--- a/man/sd_journal_get_cursor.xml
+++ b/man/sd_journal_get_cursor.xml
@@ -44,7 +44,8 @@
 
         <refnamediv>
                 <refname>sd_journal_get_cursor</refname>
-                <refpurpose>Get cursor string for the current journal entry</refpurpose>
+                <refname>sd_journal_test_cursor</refname>
+                <refpurpose>Get cursor string for or test cursor string against the current journal entry</refpurpose>
         </refnamediv>
 
         <refsynopsisdiv>
@@ -57,6 +58,12 @@
                                 <paramdef>char ** <parameter>cursor</parameter></paramdef>
                         </funcprototype>
 
+                        <funcprototype>
+                                <funcdef>int <function>sd_journal_test_cursor</function></funcdef>
+                                <paramdef>sd_journal* <parameter>j</parameter></paramdef>
+                                <paramdef>const char * <parameter>cursor</parameter></paramdef>
+                        </funcprototype>
+
                 </funcsynopsis>
         </refsynopsisdiv>
 
@@ -66,7 +73,7 @@
                 <para><function>sd_journal_get_cursor()</function>
                 returns a cursor string for the current journal
                 entry. A cursor is a serialization of the current
-                journal position in text form. The string only
+                journal position formatted as text. The string only
                 contains printable characters and can be passed around
                 in text form. The cursor identifies a journal entry
                 globally and in a stable way and may be used to later
@@ -77,16 +84,33 @@
                 without the specific entry being available locally
                 will seek to the next closest (in terms of time)
                 available entry. The call takes two arguments: a
-                journal context object and a pointer to a
-                string pointer where the cursor string will be
-                placed. The string is allocated via libc <citerefentry><refentrytitle>malloc</refentrytitle><manvolnum>3</manvolnum></citerefentry> and should
-                be freed after use with
+                journal context object and a pointer to a string
+                pointer where the cursor string will be placed. The
+                string is allocated via libc
+                <citerefentry><refentrytitle>malloc</refentrytitle><manvolnum>3</manvolnum></citerefentry>
+                and should be freed after use with
                 <citerefentry><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para>
 
-                <para>Note that this function will not work before
+                <para>Note that
+                <function>sd_journal_get_cursor()</function> will not
+                work before
                 <citerefentry><refentrytitle>sd_journal_next</refentrytitle><manvolnum>3</manvolnum></citerefentry>
-                (or related call) has been called at least
-                once, in order to position the read pointer at a valid entry.</para>
+                (or related call) has been called at least once, in
+                order to position the read pointer at a valid
+                entry.</para>
+
+                <para><function>sd_journal_test_cursor()</function>
+                may be used to check whether the current position in
+                the journal matches the specified cursor. This is
+                useful since cursor strings do not uniquely identify
+                an entry: the same entry might be referred to by
+                multiple different cursor strings, and hence string
+                comparing cursors is not possible. Use this call to
+                verify after an invocation of
+                <citerefentry><refentrytitle>sd_journal_seek_cursor</refentrytitle><manvolnum>3</manvolnum></citerefentry>
+                whether the entry being sought to was actually found
+                in the journal or the next closest entry was used
+                instead.</para>
         </refsect1>
 
         <refsect1>
@@ -94,17 +118,21 @@
 
                 <para><function>sd_journal_get_cursor()</function>
                 returns 0 on success or a negative errno-style error
-                code.</para>
+                code. <function>sd_journal_test_cursor()</function>
+                returns positive if the current entry matches the
+                specified cursor, 0 if it does not match the specified
+                cursor or a negative errno-style error code on
+                failure.</para>
         </refsect1>
 
         <refsect1>
                 <title>Notes</title>
 
                 <para>The <function>sd_journal_get_cursor()</function>
-                interface is available as shared library, which can be
-                compiled and linked to with the
-                <literal>libsystemd-journal</literal>
-                <citerefentry><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry>
+                and <function>sd_journal_test_cursor()</function>
+                interfaces are available as shared library, which can
+                be compiled and linked to with the
+                <constant>libsystemd-journal</constant> <citerefentry><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry>
                 file.</para>
         </refsect1>