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)