summaryrefslogtreecommitdiff
path: root/man/sd_journal_get_cursor.xml
diff options
context:
space:
mode:
authorLennart Poettering <lennart@poettering.net>2012-10-10 22:39:45 +0200
committerLennart Poettering <lennart@poettering.net>2012-10-10 22:41:03 +0200
commitc6511e859c35b12de4e6fb5f58d7258d9de3b8f2 (patch)
treeedec1b14c70ba7bec4869b4ef6f9be8bf16f6a75 /man/sd_journal_get_cursor.xml
parent934a316cbf68c46f05b7ce0b35fc312eca786747 (diff)
journal: when browsing the journal via browse.html allow clicking on entries to show their details
Diffstat (limited to 'man/sd_journal_get_cursor.xml')
-rw-r--r--man/sd_journal_get_cursor.xml53
1 files changed, 41 insertions, 12 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>