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=f4db2a392aed5b329ad6cfd29ae335b70173af37;hb=ffa7cd15cd2a9e802827ef0f5762de6c22933c07;hpb=91a031725396faebf51ea7b5475532453b8d6df3 diff --git a/man/sd_journal_get_fd.xml b/man/sd_journal_get_fd.xml index f4db2a392..189d21352 100644 --- a/man/sd_journal_get_fd.xml +++ b/man/sd_journal_get_fd.xml @@ -44,8 +44,12 @@ sd_journal_get_fd - sd_journal_get_process - sd_journal_get_wait + sd_journal_reliable_fd + sd_journal_process + sd_journal_wait + SD_JOURNAL_NOP + SD_JOURNAL_APPEND + SD_JOURNAL_INVALIDATE Journal change notification interface @@ -59,6 +63,11 @@ sd_journal* j + + int sd_journal_reliable_fd + sd_journal* j + + int sd_journal_process sd_journal* j @@ -78,13 +87,37 @@ 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 + an external event loop and is signaled readable as + 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 @@ -94,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. @@ -114,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, @@ -137,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 @@ -146,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 @@ -153,7 +264,8 @@ systemd1, sd-journal3, sd_journal_open3, - sd_journal_next3 + sd_journal_next3, + poll2