sd_journal_get_cursor, sd_journal_test_cursor - Get cursor string for or test
cursor string against the current journal entry
const char *cursor);
sd_journal_get_cursor() returns a cursor string for the current journal
entry. A cursor is a serialization of the current 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 seek to it via
sd_journal_seek_cursor(3). The cursor string should be considered
opaque and not be parsed by clients. Seeking to a cursor position 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 malloc(3) and should be freed
after use with free(3).
Note that sd_journal_get_cursor() will not work before
sd_journal_next(3) (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_cursor(3) whether the entry being
sought to was actually found in the journal or the next closest entry was
sd_journal_get_cursor() returns 0 on success or a negative errno-style
error 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.
All functions listed here are thread-agnostic and only a single specific thread
may operate on a given object during its entire lifetime. It's safe to
allocate multiple independent objects and use each from a specific thread in
parallel. However, it's not safe to allocate such an object in one thread, and
operate or free it from any other, even if locking is used to ensure these
threads don't operate on it at the very same time.
These APIs are implemented as a shared library, which can be
compiled and linked to with the
libsystemd pkg-config(1) file.