sd_journal_get_cursor

systemd
Developer Lennart Poettering lennart@poettering.net
sd_journal_get_cursor 3
sd_journal_get_cursor sd_journal_test_cursor Get cursor string for or test cursor string against the current journal entry

    #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