X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?a=blobdiff_plain;f=man%2Fsd_journal_get_fd.xml;h=e57431ea9e3c964d7cdccacaf75c2641e7962e55;hb=ee531d949c2f62374fc109252f8cbe61c2b8ee39;hp=6c2660c4a4cb6d65acca0a1bb3fdf354da3c0675;hpb=19125c205aa6084c225b5c11cc6dcbe18c6dbcc0;p=elogind.git
diff --git a/man/sd_journal_get_fd.xml b/man/sd_journal_get_fd.xml
index 6c2660c4a..e57431ea9 100644
--- a/man/sd_journal_get_fd.xml
+++ b/man/sd_journal_get_fd.xml
@@ -44,8 +44,13 @@
sd_journal_get_fd
+ sd_journal_get_events
+ 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 +64,16 @@
sd_journal* j
+
+ int sd_journal_get_events
+ sd_journal* j
+
+
+
+ int sd_journal_reliable_fd
+ sd_journal* j
+
+
int sd_journal_process
sd_journal* j
@@ -78,42 +93,95 @@
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
+ an external event loop and is signaled 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. Use
+ sd_journal_get_events() for an
+ events mask to watch for. 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_get_events()
+ will return the
poll2
- where it will yield POLLIN on all changes. The call
- takes one argument: the journal context object.
+ mask to wait for. This function will return a
+ combination of POLLIN and POLLOUT and similar to fill
+ into the .events field of
+ struct pollfd.
- After each POLLIN wake-up
+ 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 poll() 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
+ called to process events. 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_get_fd(),
+ sd_journal_get_events(),
+ 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_get_events(),
+ sd_journal_reliable_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
+ 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()
+ 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 +205,8 @@
Notes
The sd_journal_get_fd(),
+ sd_journal_get_events(),
+ sd_journal_reliable_fd(),
sd_journal_process() and
sd_journal_wait() interfaces are
available as shared library, which can be compiled and
@@ -146,6 +216,68 @@
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 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;
+}
+
+ 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(j);
+ pollfd.events = sd_journal_get_events(j);
+ poll(&pollfd, 1, sd_journal_reliable_fd(j) > 0 ? -1 : 2000);
+ return sd_journal_process(j);
+}
+
+
+
See Also
@@ -153,7 +285,8 @@
systemd1,
sd-journal3,
sd_journal_open3,
- sd_journal_next3
+ sd_journal_next3,
+ poll2