X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?p=elogind.git;a=blobdiff_plain;f=man%2Fsd_journal_get_fd.xml;h=189d21352bd81a99d94af59496c65b2d0a4d1d57;hp=e3b5eaa13d13a11f37121dec1aee4a2fccb25abf;hb=ffa7cd15cd2a9e802827ef0f5762de6c22933c07;hpb=bb31a4ac1997c189a344caf554f34c6aabc71aa7 diff --git a/man/sd_journal_get_fd.xml b/man/sd_journal_get_fd.xml index e3b5eaa13..189d21352 100644 --- a/man/sd_journal_get_fd.xml +++ b/man/sd_journal_get_fd.xml @@ -44,6 +44,7 @@ sd_journal_get_fd + sd_journal_reliable_fd sd_journal_process sd_journal_wait SD_JOURNAL_NOP @@ -62,6 +63,11 @@ sd_journal* j + + int sd_journal_reliable_fd + sd_journal* j + + int sd_journal_process sd_journal* j @@ -82,12 +88,36 @@ sd_journal_get_fd() returns a file descriptor that may be asynchronously polled in an external event loop and is signaled readable as - soon as the journal changes, for example because new - entries were added. The file descriptor is suitable - for usage in + soon as the journal changes, because new entries or + files were added, rotation took place, or files have + been deleted, and similar. The file descriptor is + suitable for usage in poll2 - where it will yield POLLIN on all changes. The call - takes one argument: the journal context object. + where it will yield POLLIN on changes. The call takes + one argument: the journal context object. Note that + not all file systems are capable of generating the + necessary events for wakeups from this file descriptor + to be enirely reliable. In particular network files + systems do not generate suitable file change events in + all cases. In such a case an application should not + rely alone on wake-ups from this file descriptor but + wake up and recheck the journal in regular time + intervals, for example every 2s. To detect + cases where this is necessary, use + sd_journal_reliable_fd(), + below. + + sd_journal_reliable_fd() + may be used to check whether the wakeup events from + the file descriptor returned by + sd_journal_get_fd are sufficient + to track changes to the journal. If this call returns + 0, it is necessary to regularly recheck for journal + changes (suggestion: every 2s). If this call returns a + positive integer this is not necessary, and wakeups + from the file descriptor returned by + sd_journal_get_fd() are + sufficient as only source for wake-ups. After each POLLIN wake-up sd_journal_process() needs to be @@ -97,14 +127,19 @@ that spurious wake-ups are possible). A synchronous alternative for using - sd_journal_get_fd() and + sd_journal_get_fd(), + sd_journal_reliable_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(), + synchronously wait until the journal gets changed, + possibly using a 2s time-out if this is necessary (see + above). In either way the maximum time this call + sleeps may 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_reliable_fd(), poll() and sd_journal_process() into one. @@ -117,6 +152,15 @@ sd_journal_get_fd() returns a valid file descriptor 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() + is sufficient as sole wake-up source for journal + change events. Returns 0 if it is not sufficient and + the journal needs to be checked manually in regular + time intervals for changes. Returns a negative + errno-style error code on failure. + sd_journal_process() and sd_journal_wait() return one of SD_JOURNAL_NOP, @@ -140,6 +184,7 @@ Notes The sd_journal_get_fd(), + sd_journal_reliable_fd(), sd_journal_process() and sd_journal_wait() interfaces are available as shared library, which can be compiled and @@ -149,6 +194,69 @@ file. + + Examples + + Iterating through the journal, in a live view tracking all changes: + + #include <stdio.h> +#include <string.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 char *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, d); + } + sd_journal_close(j); + return 0; +} + + Waiting with poll() (this + example lacks all error checking for the sake of + simplicity): + + #include <sys/poll.h> +#include <systemd/sd-journal.h> + +int wait_for_changes(sd_journal *j) { + struct pollfd pollfd; + pollfd.fd = sd_journal_get_fd(); + pollfd.events = POLLIN; + poll(&pollfd, 1, sd_journal_reliable_fd() > 0 ? -1 : 2000); + return sd_journal_process(j); +} + + + + See Also @@ -156,7 +264,8 @@ systemd1, sd-journal3, sd_journal_open3, - sd_journal_next3 + sd_journal_next3, + poll2