shaba/systemd-stable
1
1
Fork 0
mirror of https://github.com/systemd/systemd-stable.git synced 2024-12-24 21:34:08 +03:00
Code

journal: add public API call sd_journal_get_events()

Browse Source 
This function should be used when filling in "struct pollfd"'s .events
field for watching the journal. It will always return POLLIN for now,
but we should keep our options open to change this later on.

This mimics libsystemd-bus' sd_bus_get_events() call with the same
purpose.
This commit is contained in:
Lennart Poettering 2013-04-04 17:22:28 +02:00
parent 7c537b2e28
commit ee531d949c
5 changed files with 64 additions and 25 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

69
man/sd_journal_get_fd.xml
View File

@ -44,6 +44,7 @@
<refnamediv>
<refname>sd_journal_get_fd</refname>
<refname>sd_journal_get_events</refname>
<refname>sd_journal_reliable_fd</refname>
<refname>sd_journal_process</refname>
<refname>sd_journal_wait</refname>
@ -63,6 +64,11 @@
<paramdef>sd_journal* <parameter>j</parameter></paramdef>
</funcprototype>
<funcprototype>
<funcdef>int <function>sd_journal_get_events</function></funcdef>
<paramdef>sd_journal* <parameter>j</parameter></paramdef>
</funcprototype>
<funcprototype>
<funcdef>int <function>sd_journal_reliable_fd</function></funcdef>
<paramdef>sd_journal* <parameter>j</parameter></paramdef>
@ -87,26 +93,35 @@
<para><function>sd_journal_get_fd()</function> 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
<citerefentry><refentrytitle>poll</refentrytitle><manvolnum>2</manvolnum></citerefentry>
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
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
<citerefentry><refentrytitle>poll</refentrytitle><manvolnum>2</manvolnum></citerefentry>. Use
<function>sd_journal_get_events()</function> 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
<function>sd_journal_reliable_fd()</function>,
below.</para>
<para><function>sd_journal_get_events()</function>
will return the
<citerefentry><refentrytitle>poll</refentrytitle><manvolnum>2</manvolnum></citerefentry>
mask to wait for. This function will return a
combination of POLLIN and POLLOUT and similar to fill
into the <literal>.events</literal> field of
<literal>struct pollfd</literal>.</para>
<para><function>sd_journal_reliable_fd()</function>
may be used to check whether the wakeup events from
the file descriptor returned by
@ -119,15 +134,15 @@
<function>sd_journal_get_fd()</function> are
sufficient as only source for wake-ups.</para>
<para>After each POLLIN wake-up
<para>After each <literal>poll()</literal> wake-up
<function>sd_journal_process()</function> 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).</para>
<para>A synchronous alternative for using
<function>sd_journal_get_fd()</function>,
<function>sd_journal_get_events()</function>,
<function>sd_journal_reliable_fd()</function> and
<function>sd_journal_process()</function> is
<function>sd_journal_wait()</function>. It will
@ -139,17 +154,23 @@
<literal>(uint64_t) -1</literal> to wait
indefinitely. Internally this call simply combines
<function>sd_journal_get_fd()</function>,
<function>sd_journal_get_events()</function>,
<function>sd_journal_reliable_fd()</function>,
<function>poll()</function> and
<function>sd_journal_process()</function> into
one.</para>
</refsect1>
<refsect1>
<title>Return Value</title>
<para><function>sd_journal_get_fd()</function> returns a valid file descriptor on success or a negative errno-style error
<para><function>sd_journal_get_fd()</function> returns
a valid file descriptor on success or a negative
errno-style error code.</para>
<para><function>sd_journal_get_events()</function>
returns a combination of POLLIN, POLLOUT and suchlike
on success or a negative errno-style error
code.</para>
<para><function>sd_journal_reliable_fd()</function>
@ -184,6 +205,7 @@
<title>Notes</title>
<para>The <function>sd_journal_get_fd()</function>,
<function>sd_journal_get_events()</function>,
<function>sd_journal_reliable_fd()</function>,
<function>sd_journal_process()</function> and
<function>sd_journal_wait()</function> interfaces are
@ -249,14 +271,13 @@ int main(int argc, char *argv[]) {
int wait_for_changes(sd_journal *j) {
struct pollfd pollfd;
pollfd.fd = sd_journal_get_fd(j);
pollfd.events = POLLIN;
pollfd.events = sd_journal_get_events(j);
poll(&amp;pollfd, 1, sd_journal_reliable_fd(j) &gt; 0 ? -1 : 2000);
return sd_journal_process(j);
}
</programlisting>
</refsect1>
<refsect1>
<title>See Also</title>

1
src/journal/journalctl.c
View File

@ -27,7 +27,6 @@
#include <stdio.h>
#include <unistd.h>
#include <stdlib.h>
#include <sys/poll.h>
#include <time.h>
#include <getopt.h>
#include <signal.h>

5
src/journal/libsystemd-journal.sym
View File

@ -93,3 +93,8 @@ LIBSYSTEMD_JOURNAL_198 {
global:
sd_journal_reliable_fd;
} LIBSYSTEMD_JOURNAL_196;
LIBSYSTEMD_JOURNAL_201 {
global:
sd_journal_get_events;
} LIBSYSTEMD_JOURNAL_198;

13
src/journal/sd-journal.c
View File

@ -1981,6 +1981,19 @@ _public_ int sd_journal_get_fd(sd_journal *j) {
return j->inotify_fd;
}
_public_ int sd_journal_get_events(sd_journal *j) {
int fd;
if (!j)
return -EINVAL;
fd = sd_journal_get_fd(j);
if (fd < 0)
return fd;
return POLLIN;
}
static void process_inotify_event(sd_journal *j, struct inotify_event *e) {
Directory *d;
int r;

1
src/systemd/sd-journal.h
View File

@ -127,6 +127,7 @@ int sd_journal_enumerate_unique(sd_journal *j, const void **data, size_t *l);
void sd_journal_restart_unique(sd_journal *j);
int sd_journal_get_fd(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);
int sd_journal_wait(sd_journal *j, uint64_t timeout_usec);