SD-JOURNAL(3)

📦
version 261.3 · 15 versions
, in ubuntu stonking

💖 SD-JOURNAL(3) — the sd-journal manual, bestie edition 💖

okay so you found the sd-journal page (section 3, the library one, not the shell command one) and honestly? you're about to have a great time. this is the whole vibe of talking to the journal from C. let's go ✨

🌸 NAME 🌸

sd-journal — the APIs for submitting and querying log entries to and from the journal. that's it, that's the whole thing, and it's iconic 💅

🦋 SYNOPSIS 🦋

#include <systemd/sd-journal.h>
pkg-config --cflags --libs libsystemd

like, that's the two lines you need. the include and the pkg-config call. no cap, that's the whole entry fee 🎀

👑 DESCRIPTION 👑

sd-journal.h is part of libsystemd(3) and it hands you the APIs to submit log entries and to query them back out. the APIs it exposes are doing double duty, and the way that it's doing both at once is honestly so main character:

  • it acts as a client for the systemd-journald.service(8) journal service ✨
  • and it also acts as a parser for the journal files sitting on disk 💾

so yeah, same header, two whole personalities. we love a versatile icon.

for the actual details on the functions implemented, go read these, they're all linked and all relevant:

and if you'd rather not write C at all (valid, honestly), there's command line access too:

  • want to submit entries to the journal from the terminal? that's systemd-cat(1) 🐱
  • want to query entries from the journal? that's journalctl(1), the goat 🐐

🧚 THREAD SAFETY 🧚

okay listen, this part matters, don't skip it 🙈

the functions that operate on sd_journal objects are thread agnostic — meaning a given sd_journal pointer may only be used from one thread at a time, but multiple independent threads may use multiple objects concurrently. so like, one pointer per thread, but many pointers, many threads, all good. it's giving healthy boundaries 💅

but some functions are built different — they're fully thread-safe and may be called from multiple threads in parallel:

those ones you can just spam from everywhere. no thoughts, head empty, thread-safe 🫶

⭐ OPTIONAL DEPENDENCIES ⭐

depending on which build-time options are enabled, functions that operate on sd_journal objects might cause optional shared libraries to be dynamically loaded via dlopen(3). which libraries? things like:

  • decompression libraries — xz, lz4, zstd 🗜️
  • cryptographic libraries — gcrypt 🔐

so yeah, your build config decides whether those get pulled in at runtime. surprise mechanics, but make it libraries 💀

💜 NOTES 💜

the functions described here are available as a shared library, which you can compile against and link to with the libsystemd pkg-config(1) file. that's the pkg-config line from the synopsis, told you it was important 🎀

⚠️ okay real talk, important caveat: the code described here uses getenv(3), which is declared to be not multi-thread-safe. this means the code calling the functions described here must not call setenv(3) from a parallel thread. it is recommended to only do calls to setenv() from an early phase of the program when no other threads have been started. so set your env vars first, then start your threads. order matters, bestie, do not test this 😭

🌈 SEE ALSO 🌈

the whole friend group, all together, as it should be:

okay that's the whole page, you're officially journal-pilled 🍓 this little beauty is from systemd 261.3 — go forth and log things, ily, bye 💖✨🦋

📦 where this page comes from