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=764f716a17efb3aa0c282a4f6f2e00b193b8e5f9;hp=3fc9c5f5b5cde594cd21d81465a49bfe07592b5a;hb=86198b2788e56fd05959c2dce670d1646bf99bcd;hpb=1d98d9a62c16c8282d02942d80e025ceec962c9b diff --git a/man/sd_journal_get_fd.xml b/man/sd_journal_get_fd.xml index 3fc9c5f5b..764f716a1 100644 --- a/man/sd_journal_get_fd.xml +++ b/man/sd_journal_get_fd.xml @@ -44,9 +44,11 @@ sd_journal_get_fd - sd_journal_reliable_fd + sd_journal_get_events + sd_journal_get_timeout sd_journal_process sd_journal_wait + sd_journal_reliable_fd SD_JOURNAL_NOP SD_JOURNAL_APPEND SD_JOURNAL_INVALIDATE @@ -64,8 +66,14 @@ - int sd_journal_reliable_fd + int sd_journal_get_events + sd_journal* j + + + + int sd_journal_get_timeout sd_journal* j + uint64_t* timeout_usec @@ -79,6 +87,11 @@ uint64_t timeout_usec + + int sd_journal_reliable_fd + sd_journal* j + + @@ -87,95 +100,147 @@ 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, 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 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 + 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 for changes to + be noticed immediately. 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 + all cases. Cases like this can be detected with sd_journal_reliable_fd(), - below. + below. sd_journal_get_timeout() + will ensure in these cases that wake-ups happen + frequently enough for changes to be noticed, although + with a certain latency. + + sd_journal_get_events() + will return the poll() 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. + + sd_journal_get_timeout() + will return a timeout value for usage in + poll(). This returns a value in + microseconds since the epoch of + CLOCK_MONOTONIC for timing out + poll() in + timeout_usec. See + clock_gettime2 + for details about + CLOCK_MONOTONIC. If there is no + timeout to wait for, this will fill in + (uint64_t) -1 instead. Note that + poll() takes a relative timeout + in milliseconds rather than an absolute timeout in + microseconds. To convert the absolute 'us' timeout + into relative 'ms', use code like the + following: + + uint64_t t; +int msec; +sd_journal_get_timeout(m, &t); +if (t == (uint64_t) -1) + msec = -1; +else { + struct timespec ts; + uint64_t n; + clock_getttime(CLOCK_MONOTONIC, &ts); + n = (uint64_t) ts.tv_sec * 1000000 + ts.tv_nsec / 1000; + msec = t > n ? (int) ((t - n + 999) / 1000) : 0; +} - 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 + The code above does not do any error checking + for brevity's sake. The calculated msec + integer can be passed directly as + poll()'s timeout + parameter. + + 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(), - sd_journal_reliable_fd() and + sd_journal_get_events(), + sd_journal_get_timeout() and sd_journal_process() is sd_journal_wait(). It will - 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(), + synchronously wait until the journal gets changed. 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_get_timeout(), poll() and sd_journal_process() into one. + sd_journal_reliable_fd() + may be used to check whether the wakeup events from + the file descriptor returned by + sd_journal_get_fd() are known to + be immediately triggered. On certain file systems + where file change events from the OS are not available + (such as NFS) changes need to be polled for + repeatedly, and hence are detected only with a certain + latency. This call will return a positive value if the + journal changes are detected immediately and zero when + they need to be polled for and hence might be noticed + only with a certain latency. Note that there's usually + no need to invoke this function directly as + sd_journal_get_timeout() on these + file systems will ask for timeouts explicitly + anyway. Return Value - sd_journal_get_fd() returns a valid file descriptor on success or a negative errno-style error - code. + 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. + will generate wake-ups immediately for all journal + changes. Returns 0 if there might be a latency + involved. sd_journal_process() and sd_journal_wait() return one of - SD_JOURNAL_NOP, - SD_JOURNAL_APPEND or - SD_JOURNAL_INVALIDATE on success or + 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 + SD_JOURNAL_NOP is returned, the + journal did not 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. 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 + 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. @@ -184,13 +249,13 @@ 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 linked to with the - libsystemd-journal - pkg-config1 + libsystemd-journal pkg-config1 file. @@ -248,15 +313,27 @@ int main(int argc, char *argv[]) { int wait_for_changes(sd_journal *j) { struct pollfd pollfd; + int msec; + + sd_journal_get_timeout(m, &t); + if (t == (uint64_t) -1) + msec = -1; + else { + struct timespec ts; + uint64_t n; + clock_getttime(CLOCK_MONOTONIC, &ts); + n = (uint64_t) ts.tv_sec * 1000000 + ts.tv_nsec / 1000; + msec = t > n ? (int) ((t - n + 999) / 1000) : 0; + } + pollfd.fd = sd_journal_get_fd(j); - pollfd.events = POLLIN; - poll(&pollfd, 1, sd_journal_reliable_fd(j) > 0 ? -1 : 2000); + pollfd.events = sd_journal_get_events(j); + poll(&pollfd, 1, msec); return sd_journal_process(j); } - See Also @@ -265,7 +342,8 @@ int wait_for_changes(sd_journal *j) { sd-journal3, sd_journal_open3, sd_journal_next3, - poll2 + poll2, + clock_gettime2