- <para>The code above does not do any error checking
- for brevity's sake. The calculated <varname>msec</varname>
- integer can be passed directly as
- <function>poll()</function>'s timeout
- parameter.</para>
-
- <para>After each <function>poll()</function> wake-up
- <function>sd_journal_process()</function> needs to be
- 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_get_timeout()</function> and
- <function>sd_journal_process()</function> is
- <function>sd_journal_wait()</function>. It will
- synchronously wait until the journal gets changed. The
- maximum time this call sleeps may be controlled with
- the <parameter>timeout_usec</parameter>
- parameter. Pass <constant>(uint64_t) -1</constant> to
- wait indefinitely. Internally this call simply
- combines <function>sd_journal_get_fd()</function>,
- <function>sd_journal_get_events()</function>,
- <function>sd_journal_get_timeout()</function>,
- <function>poll()</function> and
- <function>sd_journal_process()</function> into
- one.</para>
-
- <para><function>sd_journal_reliable_fd()</function>
- may be used to check whether the wakeup events from
- the file descriptor returned by
- <function>sd_journal_get_fd()</function> 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
- <function>sd_journal_get_timeout()</function> on these
- file systems will ask for timeouts explicitly
- anyway.</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 code.</para>
-
- <para><function>sd_journal_get_events()</function>
- returns a combination of <constant>POLLIN</constant>,
- <constant>POLLOUT</constant> and suchlike on success or
- a negative errno-style error code.</para>
-
- <para><function>sd_journal_reliable_fd()</function>
- returns a positive integer if the file descriptor
- returned by <function>sd_journal_get_fd()</function>
- will generate wake-ups immediately for all journal
- changes. Returns 0 if there might be a latency
- involved.</para>
-
- <para><function>sd_journal_process()</function> and
- <function>sd_journal_wait()</function> return one of
- <constant>SD_JOURNAL_NOP</constant>,
- <constant>SD_JOURNAL_APPEND</constant> or
- <constant>SD_JOURNAL_INVALIDATE</constant> on success or
- a negative errno-style error code. If
- <constant>SD_JOURNAL_NOP</constant> is returned, the
- journal did not change since the last invocation. If
- <constant>SD_JOURNAL_APPEND</constant> is returned, new
- entries have been appended to the end of the
- journal. If <constant>SD_JOURNAL_INVALIDATE</constant>,
- 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 <constant>SD_JOURNAL_APPEND</constant>, it is
- sufficient to simply continue reading at the previous
- end of the journal.</para>
- </refsect1>
-
- <refsect1>
- <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
- available as a shared library, which can be compiled and
- linked to with the
- <constant>libsystemd</constant> <citerefentry><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry>
- file.</para>
- </refsect1>
-
- <refsect1>
- <title>Examples</title>
-
- <para>Iterating through the journal, in a live view tracking all changes:</para>
-
- <programlisting>#include <stdio.h>
+ <para>The code above does not do any error checking for brevity's
+ sake. The calculated <varname>msec</varname> integer can be passed
+ directly as <function>poll()</function>'s timeout
+ parameter.</para>
+
+ <para>After each <function>poll()</function> wake-up
+ <function>sd_journal_process()</function> needs to be 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_get_timeout()</function> and
+ <function>sd_journal_process()</function> is
+ <function>sd_journal_wait()</function>. It will synchronously wait
+ until the journal gets changed. The maximum time this call sleeps
+ may be controlled with the <parameter>timeout_usec</parameter>
+ parameter. Pass <constant>(uint64_t) -1</constant> to wait
+ indefinitely. Internally this call simply combines
+ <function>sd_journal_get_fd()</function>,
+ <function>sd_journal_get_events()</function>,
+ <function>sd_journal_get_timeout()</function>,
+ <function>poll()</function> and
+ <function>sd_journal_process()</function> into one.</para>
+
+ <para><function>sd_journal_reliable_fd()</function> may be used to
+ check whether the wakeup events from the file descriptor returned
+ by <function>sd_journal_get_fd()</function> 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 <function>sd_journal_get_timeout()</function> on these
+ file systems will ask for timeouts explicitly anyway.</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
+ code.</para>
+
+ <para><function>sd_journal_get_events()</function> returns a
+ combination of <constant>POLLIN</constant>,
+ <constant>POLLOUT</constant> and suchlike on success or a negative
+ errno-style error code.</para>
+
+ <para><function>sd_journal_reliable_fd()</function> returns a
+ positive integer if the file descriptor returned by
+ <function>sd_journal_get_fd()</function> will generate wake-ups
+ immediately for all journal changes. Returns 0 if there might be a
+ latency involved.</para>
+
+ <para><function>sd_journal_process()</function> and
+ <function>sd_journal_wait()</function> return one of
+ <constant>SD_JOURNAL_NOP</constant>,
+ <constant>SD_JOURNAL_APPEND</constant> or
+ <constant>SD_JOURNAL_INVALIDATE</constant> on success or a
+ negative errno-style error code. If
+ <constant>SD_JOURNAL_NOP</constant> is returned, the journal did
+ not change since the last invocation. If
+ <constant>SD_JOURNAL_APPEND</constant> is returned, new entries
+ have been appended to the end of the journal. If
+ <constant>SD_JOURNAL_INVALIDATE</constant>, 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 <constant>SD_JOURNAL_APPEND</constant>, it is
+ sufficient to simply continue reading at the previous end of the
+ journal.</para>
+ </refsect1>
+
+ <refsect1>
+ <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 available as
+ a shared library, which can be compiled and linked to with the
+ <constant>libsystemd</constant> <citerefentry project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry>
+ file.</para>
+ </refsect1>
+
+ <refsect1>
+ <title>Examples</title>
+
+ <para>Iterating through the journal, in a live view tracking all
+ changes:</para>
+
+ <programlisting>#include <stdio.h>