SD_JOURNAL_GET_CURSOR(3)

💖 SD_JOURNAL_GET_CURSOR(3) 💖

okay so bestie, welcome to the sd_journal_get_cursor page in the sd_journal_get_cursor section of the manual — yes the manual name is a whole vibe and we're just living in it. sit down, hydrate, let's talk about cursors 🌸

---

✨ NAME ✨

sd_journal_get_cursor, sd_journal_test_cursor — get a cursor string for the current journal entry, or test a cursor string against it. that's it, that's the whole thing, but it's lowkey important 🫶

---

✨ SYNOPSIS ✨

#include <systemd/sd-journal.h>

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

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

look at these two little icons. chefs kiss. 👑

---

✨ DESCRIPTION ✨

🎀 sd_journal_get_cursor()

this one returns a cursor string for the current journal entry. so what even is a cursor? it's a serialization of the current journal position, formatted as text. that's the whole definition, no cap.

the string only contains printable characters, so you can absolutely pass it around in text form like a little note in the group chat. 📝 a cursor identifies a journal entry globally and in a stable way, and you can later seek to it via sd_journal_seek_cursor(3).

🙈 the cursor string should be considered opaque — do not parse it, bestie. it's giving "not for you to understand, just for you to use."

and heads up: if you seek to a cursor position but that specific entry isn't available locally, it'll seek to the next closest (in terms of time) available entry. slay, but also know that.

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 you should free it after use with free(3). literally do not forget. 😭

the ret_cursor parameter may be passed as NULL — in which case the cursor string is not generated, but the return value will still tell you whether the journal context is currently positioned on an entry, and thus has a cursor associated. sneaky useful. 💅

🦋 sd_journal_test_cursor()

use this one to check whether the current position in the journal matches the specified cursor.

and why would you need that? because cursor strings do not uniquely identify an entry — the same entry might be referred to by multiple different cursor strings, so string comparing cursors is literally not possible. not me learning that the hard way. 💀

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 whether the next closest entry was used instead. vibe check for your seek. ✅

⚠️ important: sd_journal_get_cursor() and sd_journal_test_cursor() will not work before sd_journal_next(3) (or one of the other functions which move to an entry) has been called at least once to position the read pointer at a valid entry. you gotta move first, then you can look. 🚶‍♀️

---

✨ RETURN VALUE ✨

sd_journal_get_cursor() returns 0 on success or a negative errno-style error code. classic.

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. three whole moods. 🌈

💜 Errors

returned errors may indicate the following problems:

• -EADDRNOTAVAIL — the journal context is currently not positioned on any entry, and hence no cursor string can be generated. you're nowhere, bestie. 🫥
• -EINVAL — the journal context parameter is NULL. yeah. that'll do it.
• -ECHILD — the journal context object has been allocated in a different process than it is being used in now. it's not you, it's the fork. 😭

---

✨ NOTES ✨

all functions listed here are thread-agnostic, and only a single thread may operate on a given object at any given time. different threads may access the same object at different times, and multiple independent objects may be used from different threads in parallel. so, like, share responsibly. 🧚

functions described here are available as a shared library, which can be compiled against and linked to with the libsystemd pkg-config(1) file. link it, love it, live it. 🎀

---

✨ HISTORY ✨

• sd_journal_get_cursor() was added in version 187. an icon, an elder, a legend. 👑
• sd_journal_test_cursor() was added in version 195. the sequel that ate. 🔥

---

✨ SEE ALSO ✨

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

go read them, i'll wait. 💜

---

and that's the page, bestie — this iconic little rewrite comes to you courtesy of systemd 261.3 and the SD_JOURNAL_GET_CURSOR(3) era of the manual. mwah. 💅✨