journal: add public API call sd_journal_get_events()

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.

diff --git a/man/sd_journal_get_fd.xml b/man/sd_journal_get_fd.xml
index 3fc9c5f5b5cde594cd21d81465a49bfe07592b5a..e57431ea9e3c964d7cdccacaf75c2641e7962e55 100644 (file)
--- 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>
 
         <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>
                 <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>
 
                                 <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>
                         <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
 
                 <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>
 
                 <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
                 <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>
 
                 <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
                 <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>,
                 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
                 <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>,
                 <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>
                 <function>sd_journal_reliable_fd()</function>,
                 <function>poll()</function> and
                 <function>sd_journal_process()</function> into
                 one.</para>

-

         </refsect1>
 
         <refsect1>
                 <title>Return Value</title>
 
         </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>
                 code.</para>
 
                 <para><function>sd_journal_reliable_fd()</function>


@@ -184,6 +205,7 @@
                 <title>Notes</title>
 
                 <para>The <function>sd_journal_get_fd()</function>,
                 <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
                 <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);
 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>
 
         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>
 
         <refsect1>
                 <title>See Also</title>
 

diff --git a/src/journal/journalctl.c b/src/journal/journalctl.c
index 1f26787cf7449b4449c8ca5b135988f742b3091c..86895b8f5b86c7cd3aaec07d356d694b534f102a 100644 (file)
--- a/src/journal/journalctl.c
+++ b/src/journal/journalctl.c
@@ -27,7 +27,6 @@
 #include <stdio.h>
 #include <unistd.h>
 #include <stdlib.h>
 #include <stdio.h>
 #include <unistd.h>
 #include <stdlib.h>

-#include <sys/poll.h>

 #include <time.h>
 #include <getopt.h>
 #include <signal.h>
 #include <time.h>
 #include <getopt.h>
 #include <signal.h>

diff --git a/src/journal/libsystemd-journal.sym b/src/journal/libsystemd-journal.sym
index fbe41501f0ebeb4b84e4e6fb81425649dfa9d72d..e241318cb039f8dd0817747f4d095d992a6c13f8 100644 (file)
--- a/src/journal/libsystemd-journal.sym
+++ b/src/journal/libsystemd-journal.sym
@@ -93,3 +93,8 @@ LIBSYSTEMD_JOURNAL_198 {
 global:
         sd_journal_reliable_fd;
 } LIBSYSTEMD_JOURNAL_196;
 global:
         sd_journal_reliable_fd;
 } LIBSYSTEMD_JOURNAL_196;

+
+LIBSYSTEMD_JOURNAL_201 {
+global:
+        sd_journal_get_events;
+} LIBSYSTEMD_JOURNAL_198;

diff --git a/src/journal/sd-journal.c b/src/journal/sd-journal.c
index bb9967193474d26e41375f51c4e3bca4405754ed..3eba4cd0d1e8ed1964e43d1c91e493759575dce3 100644 (file)
--- a/src/journal/sd-journal.c
+++ b/src/journal/sd-journal.c
@@ -1981,6 +1981,19 @@ _public_ int sd_journal_get_fd(sd_journal *j) {
         return j->inotify_fd;
 }
 
         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;
 static void process_inotify_event(sd_journal *j, struct inotify_event *e) {
         Directory *d;
         int r;

diff --git a/src/systemd/sd-journal.h b/src/systemd/sd-journal.h
index 2e8d2d882f5589adaf3bcfff8d922af50571a361..aa7693af70ba57b454d9e8241f910951cadc8ead 100644 (file)
--- a/src/systemd/sd-journal.h
+++ b/src/systemd/sd-journal.h
@@ -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);
 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);
 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);