NAME

       sd_journal_get_cursor, sd_journal_test_cursor - Get cursor string for or test cursor string against the
       current journal entry

SYNOPSIS

       #include <systemd/sd-journal.h>

       int sd_journal_get_cursor(sd_journal *j, char **cursor);

       int sd_journal_test_cursor(sd_journal *j, const char *cursor);

DESCRIPTION

       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 used instead.

RETURN VALUE

       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.

NOTES

       All functions listed here are thread-agnostic and only a single thread may operate on a given sd_journal
       object.

       The sd_journal_get_cursor() and sd_journal_test_cursor() interfaces are available as a shared library,
       which can be compiled and linked to with the libsystemd pkg-config(1) file.

SEE ALSO

       systemd(1), sd-journal(3), sd_journal_open(3), sd_journal_seek_cursor(3)