SD_JOURNAL_GET_FD(3)

📦
version 261.3 · 16 versions
, in ubuntu stonking

💖 SD_JOURNAL_GET_FD(3) — the journal change-notification girlies 💖

okay so bestie, this whole page is from the sd_journal_get_fd manual, section 3 of the systemd docs, and it's literally the entire friend group of functions that tell you "hey, the journal changed!!" so you don't have to sit there refreshing like a clown. we've got sd_journal_get_fd, sd_journal_get_events, sd_journal_get_timeout, sd_journal_process, sd_journal_wait, sd_journal_reliable_fd, plus the three little mood-ring constants SD_JOURNAL_NOP, SD_JOURNAL_APPEND, and SD_JOURNAL_INVALIDATE. it's giving journal change notification interface and we're obsessed 🦋

✨ NAME ✨

sd_journal_get_fd, sd_journal_get_events, sd_journal_get_timeout, sd_journal_process, sd_journal_wait, sd_journal_reliable_fd, SD_JOURNAL_NOP, SD_JOURNAL_APPEND, SD_JOURNAL_INVALIDATE — the whole journal change notification interface, no cap 💅

🌸 SYNOPSIS 🌸

#include <systemd/sd-journal.h>

int sd_journal_get_fd(sd_journal *j);

int sd_journal_get_events(sd_journal *j);

int sd_journal_get_timeout(sd_journal *j, uint64_t *timeout_usec);

int sd_journal_process(sd_journal *j);

int sd_journal_wait(sd_journal *j, uint64_t timeout_usec);

int sd_journal_reliable_fd(sd_journal *j);

🎀 DESCRIPTION 🎀

the fd girlie herself: sd_journal_get_fd()

so sd_journal_get_fd() hands you a file descriptor that you can poll asynchronously from your external event loop, and it gets signaled the second the journal changes — like, new entries or files got added, rotation happened, files got deleted, that whole vibe. it's totally suitable for use in poll(2). and to know what events to watch for, you use sd_journal_get_events(). the call takes exactly one argument: the journal context object j.

⚠️ heads up bestie: not all file systems can generate the necessary events for wakeups from this fd, so changes might not be noticed immediately. network file systems especially do not generate suitable file change events in all cases. 😭 you can detect cases like that with sd_journal_reliable_fd() (below). and sd_journal_get_timeout() will make sure that, in these cases, wake-ups still happen frequently enough for changes to be noticed — just with a certain latency. it's giving "we got there eventually" 💀

sd_journal_get_events()

sd_journal_get_events() returns the poll() mask to wait for. it gives you a combination of POLLIN and POLLOUT and similar, ready to drop into the .events field of struct pollfd. slay ✨

sd_journal_get_timeout()

sd_journal_get_timeout() returns a timeout value for usage in poll(). specifically, it returns a value in microseconds since the epoch of CLOCK_MONOTONIC for timing out poll() in timeout_usec. peep clock_gettime(2) for the deets on CLOCK_MONOTONIC. if there's no timeout to wait for, it fills in (uint64_t) -1 instead.

💡 the catch: poll() takes a relative timeout in milliseconds, not an absolute timeout in microseconds. so to convert that absolute 'us' timeout into relative 'ms', use code like this:
uint64_t t;
int msec;
sd_journal_get_timeout(m, &t);
if (t == (uint64_t) -1)
  msec = -1;
else {
  struct timespec ts;
  uint64_t n;
  clock_gettime(CLOCK_MONOTONIC, &ts);
  n = (uint64_t) ts.tv_sec * 1000000 + ts.tv_nsec / 1000;
  msec = t > n ? (int) ((t - n + 999) / 1000) : 0;
}

the code above does not do any error checking, for brevity's sake (yes, we know, don't come for us 🙈). the calculated msec integer can be passed directly as poll()'s timeout parameter. iconic.

sd_journal_process()

after each poll() wake-up, you need to call sd_journal_process() to process events. this call also tells you what kind of change has been detected (see below; note that spurious wake-ups are possible — yes, it can wake up just to say nothing, main character energy fr).

sd_journal_wait() — the synchronous alternative

a synchronous alternative to using sd_journal_get_fd(), sd_journal_get_events(), sd_journal_get_timeout(), and sd_journal_process() is sd_journal_wait(). it synchronously waits until the journal gets changed. the maximum time this call sleeps can be controlled with the timeout_usec parameter — pass (uint64_t) -1 to wait indefinitely. internally this call simply combines sd_journal_get_fd(), sd_journal_get_events(), sd_journal_get_timeout(), poll(), and sd_journal_process() into one. one call, all the vibes 🫶

sd_journal_reliable_fd()

sd_journal_reliable_fd() checks whether the wake-up events from the file descriptor returned by sd_journal_get_fd() are known to be quickly triggered. on certain file systems where file change events from the OS are not available (such as NFS), changes need to be polled for repeatedly, and hence are detected only with a considerable latency 😴. this call returns a positive value if the journal changes are detected quickly, and zero when they need to be polled for. note that there's usually no need to invoke this function directly, since sd_journal_get_timeout() will request appropriate timeouts anyway.

🫧 also real talk: all of the above change notification interfaces do not report changes instantly. latencies are introduced for multiple reasons — as mentioned, certain storage backends require time-based polling; in other cases wake-ups are optimized by coalescing events; and the OS introduces additional IO/CPU scheduling latencies. it's not slacking, it's just ✨scheduling✨.

👑 RETURN VALUE 👑

  • sd_journal_get_fd() — returns a valid file descriptor on success, or a negative errno-style error code. 💖
  • sd_journal_get_events() — returns a combination of POLLIN, POLLOUT and suchlike on success, or a negative errno-style error code.
  • sd_journal_reliable_fd() — returns a positive integer if the file descriptor returned by sd_journal_get_fd() will generate wake-ups immediately for all journal changes. returns 0 if there might be a latency involved.
  • sd_journal_process() and sd_journal_wait() — return a negative errno-style error code, or one of SD_JOURNAL_NOP, SD_JOURNAL_APPEND, or SD_JOURNAL_INVALIDATE on success:
    • if SD_JOURNAL_NOP is returned, the journal did not change since the last invocation. literally nothing happened, go back to sleep 💤
    • if SD_JOURNAL_APPEND is returned, new entries have been appended to the end of the journal. in this case, it's sufficient to simply continue reading at the previous end location of the journal to read the newly added entries. easy! 🍓
    • if SD_JOURNAL_INVALIDATE, journal files were added to or removed from the set of journal files watched (e.g. due to rotation or vacuuming), and thus entries might have appeared or disappeared at arbitrary places in the log stream — possibly before or after the previous end of the log stream. 😭 if SD_JOURNAL_INVALIDATE is returned, live-view UIs that want to reflect on screen the precise state of the log data on disk should probably refresh their entire display (relative to the cursor of the log entry on the top of the screen). programs only interested in a strictly sequential stream of log data may treat SD_JOURNAL_INVALIDATE the same way as SD_JOURNAL_APPEND, thus ignoring any changes to the log view earlier than the old end of the log stream. pick your fighter 💅

🌈 SIGNAL SAFETY 🌈

in general, sd_journal_get_fd(), sd_journal_get_events(), and sd_journal_get_timeout() are not "async signal safe" in the meaning of signal-safety(7). but here's the cute part: only the first call to any of those three functions performs unsafe operations, so subsequent calls are safe. so it's a one-time risk, like sending that text 🫣

sd_journal_process() and sd_journal_wait() are not safe. sd_journal_reliable_fd() is safe. periodt.

⭐ 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 yes, share the vibes, but not simultaneously on the same object 🧚

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 💜

🦋 EXAMPLES 🦋

example one: iterating through the journal, live view tracking all changes

/* SPDX-License-Identifier: MIT-0 */

#include <errno.h>
#include <stdio.h>
#include <systemd/sd-journal.h>

int main(int argc, char *argv[]) {
  int r;
  sd_journal *j;

  r = sd_journal_open(&j, SD_JOURNAL_LOCAL_ONLY);
  if (r < 0) {
    fprintf(stderr, "Failed to open journal: %s\n", strerror(-r));
    return 1;
  }

  for (;;)  {
    const void *d;
    size_t l;
    r = sd_journal_next(j);
    if (r < 0) {
      fprintf(stderr, "Failed to iterate to next entry: %s\n", strerror(-r));
      break;
    }
    if (r == 0) {
      /* Reached the end, let's wait for changes, and try again */
      r = sd_journal_wait(j, (uint64_t) -1);
      if (r < 0) {
        fprintf(stderr, "Failed to wait for changes: %s\n", strerror(-r));
        break;
      }
      continue;
    }
    r = sd_journal_get_data(j, "MESSAGE", &d, &l);
    if (r < 0) {
      fprintf(stderr, "Failed to read message field: %s\n", strerror(-r));
      continue;
    }
    printf("%.*s\n", (int) l, (const char*) d);
  }

  sd_journal_close(j);
  return 0;
}

example two: waiting with poll()

this example lacks all error checking for the sake of simplicity (again, we know 🙈):

/* SPDX-License-Identifier: MIT-0 */

#define _GNU_SOURCE 1
#include <poll.h>
#include <time.h>
#include <systemd/sd-journal.h>

int wait_for_changes(sd_journal *j) {
  uint64_t t;
  int msec;
  struct pollfd pollfd;

  sd_journal_get_timeout(j, &t);
  if (t == (uint64_t) -1)
    msec = -1;
  else {
    struct timespec ts;
    uint64_t n;
    clock_gettime(CLOCK_MONOTONIC, &ts);
    n = (uint64_t) ts.tv_sec * 1000000 + ts.tv_nsec / 1000;
    msec = t > n ? (int) ((t - n + 999) / 1000) : 0;
  }

  pollfd.fd = sd_journal_get_fd(j);
  pollfd.events = sd_journal_get_events(j);
  poll(&pollfd, 1, msec);
  return sd_journal_process(j);
}

🕰️ HISTORY 🕰️

  • sd_journal_get_fd(), sd_journal_process(), and sd_journal_wait() were added in version 187. og era 🫶
  • sd_journal_reliable_fd() was added in version 196.
  • sd_journal_get_events() and sd_journal_get_timeout() were added in version 201.

💜 SEE ALSO 💜

systemd(1), sd-journal(3), sd_journal_open(3), sd_journal_next(3), poll(2), clock_gettime(2)

and that's the whole page bestie, go forth and poll responsibly 💅✨

🌸 this has been systemd version 261.3, SD_JOURNAL_GET_FD(3), signing off — mwah, ily, see you in the event loop 🎀
📦 where this page comes from