diff options
Diffstat (limited to 'man/sd_journal_get_fd.xml')
| -rw-r--r-- | man/sd_journal_get_fd.xml | 69 |
1 files changed, 45 insertions, 24 deletions
diff --git a/man/sd_journal_get_fd.xml b/man/sd_journal_get_fd.xml index 3fc9c5f5b5..e57431ea9e 100644 --- a/man/sd_journal_get_fd.xml +++ b/man/sd_journal_get_fd.xml @@ -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> @@ -64,6 +65,11 @@ </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> </funcprototype> @@ -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(&pollfd, 1, sd_journal_reliable_fd(j) > 0 ? -1 : 2000); return sd_journal_process(j); } </programlisting> </refsect1> - <refsect1> <title>See Also</title> |