X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?a=blobdiff_plain;f=man%2Fsd_journal_get_fd.xml;h=189d21352bd81a99d94af59496c65b2d0a4d1d57;hb=7a14d67f7618787a0b829eb360b41a3889801f74;hp=f4db2a392aed5b329ad6cfd29ae335b70173af37;hpb=91a031725396faebf51ea7b5475532453b8d6df3;p=elogind.git
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