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=189d21352bd81a99d94af59496c65b2d0a4d1d57;hpb=f274ece0f76b5709408821e317e87aef76123db6;p=elogind.git

diff --git a/man/sd_journal_get_fd.xml b/man/sd_journal_get_fd.xml
index 189d21352..e57431ea9 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>
@@ -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
@@ -212,7 +234,7 @@ int main(int argc, char *argv[]) {
                 return 1;
         }
         for (;;)  {
-                const char *d;
+                const void *d;
                 size_t l;
                 r = sd_journal_next(j);
                 if (r &lt; 0) {
@@ -233,7 +255,7 @@ int main(int argc, char *argv[]) {
                         fprintf(stderr, "Failed to read message field: %s\n", strerror(-r));
                         continue;
                 }
-                printf("%.*s\n", (int) l, d);
+                printf("%.*s\n", (int) l, (const char*) d);
         }
         sd_journal_close(j);
         return 0;
@@ -248,15 +270,14 @@ int main(int argc, char *argv[]) {
 
 int wait_for_changes(sd_journal *j) {
         struct pollfd pollfd;
-        pollfd.fd = sd_journal_get_fd();
-        pollfd.events = POLLIN;
-        poll(&amp;pollfd, 1, sd_journal_reliable_fd() &gt; 0 ? -1 : 2000);
+        pollfd.fd = sd_journal_get_fd(j);
+        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>