SD_JOURNAL_SEEK_HEAD(3)

📦
version 261.3 · 17 versions
, in ubuntu stonking

💅 SD_JOURNAL_SEEK_HEAD(3) — bestie's guide to seeking around the journal 💅

okay so this is the page for sd_journal_seek_head and its whole little friend group 🌸 — they all live in the sd_journal_seek_head(3) manual, and they're literally the "teleport me to a spot in the journal" squad. no cap, they're icons.

✨ NAME ✨

sd_journal_seek_head, sd_journal_seek_tail, sd_journal_seek_monotonic_usec, sd_journal_seek_realtime_usec, sd_journal_seek_cursor — seek to a position in the journal 🎯

🦋 SYNOPSIS 🦋

#include <systemd/sd-journal.h>

int sd_journal_seek_head(sd_journal *j);

int sd_journal_seek_tail(sd_journal *j);

int sd_journal_seek_monotonic_usec(sd_journal *j, sd_id128_t boot_id,
                                   uint64_t usec);

int sd_journal_seek_realtime_usec(sd_journal *j, uint64_t usec);

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

🎀 DESCRIPTION 🎀

okay so picture the journal as one giant timeline, right? these functions are how you yeet your little pointer to a specific spot on it. here's the tea, function by function:

  • sd_journal_seek_head() — seeks to the beginning of the journal. and by "beginning" i mean the position before the oldest available entry. like, you're standing just outside the door of the oldest thing. 🚪
  • sd_journal_seek_tail() — same energy, other end: seeks to the end of the journal, i.e. the position after the most recent available entry. you're past the newest thing, chilling. 💅
  • sd_journal_seek_monotonic_usec() — seeks to the position with the specified monotonic timestamp, i.e. CLOCK_MONOTONIC. ⏱️ and because monotonic time restarts on every reboot, you literally have to hand over a boot ID too (boot_id). no boot ID, no vibes.
  • sd_journal_seek_realtime_usec() — seeks to the position with the specified realtime (wallclock) timestamp, i.e. CLOCK_REALTIME. ⏰ heads up though: the realtime clock is not necessarily monotonic. and if a realtime timestamp is ambiguous? it's not defined which position gets sought to. so like… don't @ me. 🫠
  • sd_journal_seek_cursor() — seeks to the position at the specified cursor string. for the deets on cursors, go see sd_journal_get_cursor(3). and if no entry matching the specified cursor is found, the call will seek to the next closest entry (in terms of time) instead. she improvises 💁‍♀️
⚠️ big thing, do not skip: these calls do not actually make any entry the new current entry. like, they move you to the address but don't open the door. you need a separate step — a subsequent sd_journal_next(3) invocation (or a similar call) — to actually land on an entry. only then can entry data be retrieved via sd_journal_get_data(3), or an entry cursor be retrieved via sd_journal_get_cursor(3).

and if no entry exists that matches exactly the specified seek address? the next closest one is sought to, bestie:

after the seek is done and sd_journal_next(3) or a similar call has been made, you can hit up sd_journal_test_cursor(3) to verify whether the newly selected entry actually matches the cursor. vibe check for entries, basically ✅

🌈 RETURN VALUE 🌈

the functions return 0 on success, or a negative errno-style error code. slay when zero, sad when negative 😭

💜 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. multiple independent objects may be used from different threads in parallel. so like, share the object politely, or just make more objects. 🧚
  • functions described here are available as a shared library, which can be compiled against and linked to with the libsystemd pkg-config(1) file. 📚

⭐ HISTORY ⭐

sd_journal_seek_head(), sd_journal_seek_tail(), sd_journal_seek_monotonic_usec(), sd_journal_seek_realtime_usec(), and sd_journal_seek_cursor() were added in version 187. vintage icons, honestly 👑

🔥 SEE ALSO 🔥

systemd(1), sd-journal(3), sd_journal_open(3), sd_journal_next(3), sd_journal_get_data(3), sd_journal_get_cursor(3), sd_journal_get_realtime_usec(3)

that's the whole page, bestie 🫶 this cutie is from systemd 261.3, so go forth and seek responsibly 💖✨🎀

📦 where this page comes from