X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?a=blobdiff_plain;f=man%2Fsd_journal_get_cursor.xml;h=3f5483bbdaf5e295abf9fe34803b3e71483a8e45;hb=79c1afc67f973eaece8f1b7016e016bb33c256a7;hp=9e00ef7c82f28b5b1255cda321df2a5e24d34658;hpb=4a010f4e6e95964d7acaa33be768dbdb5e46d72a;p=elogind.git
diff --git a/man/sd_journal_get_cursor.xml b/man/sd_journal_get_cursor.xml
index 9e00ef7c8..3f5483bbd 100644
--- a/man/sd_journal_get_cursor.xml
+++ b/man/sd_journal_get_cursor.xml
@@ -44,7 +44,8 @@
sd_journal_get_cursor
- Get cursor string for the current journal entry
+ sd_journal_test_cursor
+ Get cursor string for or test cursor string against the current journal entry
@@ -53,8 +54,14 @@
int sd_journal_get_cursor
- sd_journal* j
- char ** cursor
+ sd_journal *j
+ char **cursor
+
+
+
+ int sd_journal_test_cursor
+ sd_journal *j
+ const char *cursor
@@ -66,7 +73,7 @@
sd_journal_get_cursor()
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 malloc3 and should
- be freed after use with
- free3.
-
- Note that this function will not work before
+ journal context object and a pointer to a string
+ pointer where the cursor string will be placed. The
+ string is allocated via libc
+ malloc3
+ and should be freed after use with
+ free3.
+
+ Note that
+ sd_journal_get_cursor() will not
+ work before
sd_journal_next3
- (or related call) has been called at least
- once, in order to position the read pointer at a valid entry.
+ (or related call) has been called at least once, in
+ order to position the read pointer at a valid
+ entry.
+
+ sd_journal_test_cursor()
+ 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
+ sd_journal_seek_cursor3
+ whether the entry being sought to was actually found
+ in the journal or the next closest entry was used
+ instead.
@@ -94,17 +118,21 @@
sd_journal_get_cursor()
returns 0 on success or a negative errno-style error
- code.
+ code. sd_journal_test_cursor()
+ 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.
Notes
The sd_journal_get_cursor()
- interface is available as shared library, which can be
- compiled and linked to with the
- libsystemd-journal
- pkg-config1
+ and sd_journal_test_cursor()
+ interfaces are available as a shared library, which can
+ be compiled and linked to with the
+ libsystemd pkg-config1
file.