SD_JOURNAL_GET_FD(3)

NAME
sd_journal_get_fd, sd_journal_process, sd_journal_wait, SD_JOURNAL_NOP, SD_JOURNAL_APPEND, SD_JOURNAL_INVALIDATE - Journal change notification interface

SYNOPSIS

#include <systemd/sd-journal.h>

int sd_journal_get_fd(sd_journal* j);

int sd_journal_process(sd_journal* j);

int sd_journal_wait(sd_journal* j, uint64_t timeout_usec);

DESCRIPTION

sd_journal_get_fd() returns a file descriptor that may be asynchronously polled in an external event loop and is signalled readable as soon as the journal changes, for example because new entries were added. The file descriptor is suitable for usage in poll(2) where it will yield POLLIN on all changes. The call takes one argument: the journal context object.

After each POLLIN wake-up sd_journal_process() needs to be called to process events and reset the readable state of the file descriptor. This call will also indicate what kind of change has been detected (see below; note that spurious wake-ups are possible).

A synchronous alternative for using sd_journal_get_fd() and sd_journal_process() is sd_journal_wait(). It will synchronously wait until the journal gets changed up to a certain time-out as specified in its second argument. Pass (uint64_t) -1 to wait indefinitely. Internally this call simply combines sd_journal_get_fd(), poll() and sd_journal_process() into one.

RETURN VALUE

sd_journal_get_fd() returns a valid file descriptor on success or a negative errno-style error code.

sd_journal_process() and sd_journal_wait() return one of SD_JOURNAL_NOP, SD_JOURNAL_APPEND or SD_JOURNAL_INVALIDATE on success or a negative errno-style error code. If SD_JOURNAL_NOP is returned the journal didn't change since the last invocation. If SD_JOURNAL_APPEND is returned new entries have been appended to the end of the journal. If SD_JOURNAL_INVALIDATE journal files were added or removed (possibly due to rotation). In the latter event live-view UIs should probably refresh their entire display while in the case of SD_JOURNAL_APPEND it is sufficient to simply continue reading at the previous end of the journal.

NOTES

The sd_journal_get_fd(), sd_journal_process() and sd_journal_wait() interfaces are available as shared library, which can be compiled and linked to with the libsystemd-journal pkg-config(1) file.

SEE ALSO

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