summaryrefslogtreecommitdiff
path: root/man
diff options
context:
space:
mode:
Diffstat (limited to 'man')
-rw-r--r--man/sd_journal_get_cursor.xml53
-rw-r--r--man/sd_journal_seek_head.xml7
2 files changed, 47 insertions, 13 deletions
diff --git a/man/sd_journal_get_cursor.xml b/man/sd_journal_get_cursor.xml
index 9e00ef7c82..354168bee2 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 seeked to was actually found
+ in the journal or the next closest entry was used
+ instead.</para>
</refsect1>
<refsect1>
@@ -94,15 +118,20 @@
<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 doesn't 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
+ and <function>sd_journal_test_cursor()</function>
+ interfaces are 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>
file.</para>
diff --git a/man/sd_journal_seek_head.xml b/man/sd_journal_seek_head.xml
index f8a4eb1d20..b10f069e83 100644
--- a/man/sd_journal_seek_head.xml
+++ b/man/sd_journal_seek_head.xml
@@ -115,7 +115,12 @@
<para><function>sd_journal_seek_cursor()</function>
seeks to the entry located at the specified cursor
string. For details on cursors see
- <citerefentry><refentrytitle>sd_journal_get_cursor</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para>
+ <citerefentry><refentrytitle>sd_journal_get_cursor</refentrytitle><manvolnum>3</manvolnum></citerefentry>. If
+ no entry matching the specified cursor is found the
+ call will seek to the next closest entry (in terms of
+ time) instead. To verify whether the newly selected
+ entry actually matches the cursor use
+ <citerefentry><refentrytitle>sd_journal_test_cursor</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para>
<para>Note that these calls do not actually make any
entry the new current entry, this needs to be done in