summaryrefslogtreecommitdiffstats
path: root/man/sd_journal_get_fd.xml
diff options
context:
space:
mode:
Diffstat (limited to 'man/sd_journal_get_fd.xml')
-rw-r--r--man/sd_journal_get_fd.xml259
1 files changed, 259 insertions, 0 deletions
diff --git a/man/sd_journal_get_fd.xml b/man/sd_journal_get_fd.xml
new file mode 100644
index 0000000..6ca45c4
--- /dev/null
+++ b/man/sd_journal_get_fd.xml
@@ -0,0 +1,259 @@
+<?xml version='1.0'?> <!--*-nxml-*-->
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
+ "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
+<!-- SPDX-License-Identifier: LGPL-2.1-or-later -->
+
+<refentry id="sd_journal_get_fd" xmlns:xi="http://www.w3.org/2001/XInclude">
+
+ <refentryinfo>
+ <title>sd_journal_get_fd</title>
+ <productname>systemd</productname>
+ </refentryinfo>
+
+ <refmeta>
+ <refentrytitle>sd_journal_get_fd</refentrytitle>
+ <manvolnum>3</manvolnum>
+ </refmeta>
+
+ <refnamediv>
+ <refname>sd_journal_get_fd</refname>
+ <refname>sd_journal_get_events</refname>
+ <refname>sd_journal_get_timeout</refname>
+ <refname>sd_journal_process</refname>
+ <refname>sd_journal_wait</refname>
+ <refname>sd_journal_reliable_fd</refname>
+ <refname>SD_JOURNAL_NOP</refname>
+ <refname>SD_JOURNAL_APPEND</refname>
+ <refname>SD_JOURNAL_INVALIDATE</refname>
+ <refpurpose>Journal change notification
+ interface</refpurpose>
+ </refnamediv>
+
+ <refsynopsisdiv>
+ <funcsynopsis>
+ <funcsynopsisinfo>#include &lt;systemd/sd-journal.h&gt;</funcsynopsisinfo>
+
+ <funcprototype>
+ <funcdef>int <function>sd_journal_get_fd</function></funcdef>
+ <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_get_timeout</function></funcdef>
+ <paramdef>sd_journal *<parameter>j</parameter></paramdef>
+ <paramdef>uint64_t *<parameter>timeout_usec</parameter></paramdef>
+ </funcprototype>
+
+ <funcprototype>
+ <funcdef>int <function>sd_journal_process</function></funcdef>
+ <paramdef>sd_journal *<parameter>j</parameter></paramdef>
+ </funcprototype>
+
+ <funcprototype>
+ <funcdef>int <function>sd_journal_wait</function></funcdef>
+ <paramdef>sd_journal *<parameter>j</parameter></paramdef>
+ <paramdef>uint64_t <parameter>timeout_usec</parameter></paramdef>
+ </funcprototype>
+
+ <funcprototype>
+ <funcdef>int <function>sd_journal_reliable_fd</function></funcdef>
+ <paramdef>sd_journal *<parameter>j</parameter></paramdef>
+ </funcprototype>
+
+ </funcsynopsis>
+ </refsynopsisdiv>
+
+ <refsect1>
+ <title>Description</title>
+
+ <para><function>sd_journal_get_fd()</function> returns a file
+ descriptor that may be asynchronously polled in 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 for changes to be noticed immediately. In particular
+ network files systems do not generate suitable file change events
+ in all cases. Cases like this can be detected with
+ <function>sd_journal_reliable_fd()</function>, below.
+ <function>sd_journal_get_timeout()</function> will ensure in these
+ cases that wake-ups happen frequently enough for changes to be
+ noticed, although with a certain latency.</para>
+
+ <para><function>sd_journal_get_events()</function> will return the
+ <function>poll()</function> mask to wait for. This function will
+ return a combination of <constant>POLLIN</constant> and
+ <constant>POLLOUT</constant> and similar to fill into the
+ <literal>.events</literal> field of <varname>struct
+ pollfd</varname>.</para>
+
+ <para><function>sd_journal_get_timeout()</function> will return a
+ timeout value for usage in <function>poll()</function>. This
+ returns a value in microseconds since the epoch of
+ <constant>CLOCK_MONOTONIC</constant> for timing out
+ <function>poll()</function> in <varname>timeout_usec</varname>.
+ See
+ <citerefentry><refentrytitle>clock_gettime</refentrytitle><manvolnum>2</manvolnum></citerefentry>
+ for details about <constant>CLOCK_MONOTONIC</constant>. If there
+ is no timeout to wait for, this will fill in <constant>(uint64_t)
+ -1</constant> instead. Note that <function>poll()</function> takes
+ a relative timeout in milliseconds rather than an absolute timeout
+ in microseconds. To convert the absolute 'us' timeout into
+ relative 'ms', use code like the following:</para>
+
+ <programlisting>uint64_t t;
+int msec;
+sd_journal_get_timeout(m, &amp;t);
+if (t == (uint64_t) -1)
+ msec = -1;
+else {
+ struct timespec ts;
+ uint64_t n;
+ clock_gettime(CLOCK_MONOTONIC, &amp;ts);
+ n = (uint64_t) ts.tv_sec * 1000000 + ts.tv_nsec / 1000;
+ msec = t > n ? (int) ((t - n + 999) / 1000) : 0;
+}</programlisting>
+
+ <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 wake-up events from
+ the file descriptor returned by <function>sd_journal_get_fd()</function> are known to be quickly
+ 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 considerable latency. This
+ call will return a positive value if the journal changes are detected quickly and zero when they need to
+ be polled for. Note that there is usually no need to invoke this function directly as
+ <function>sd_journal_get_timeout()</function> will request appropriate timeouts anyway.</para>
+
+ <para>Note that all of the above change notification interfaces do not report changes
+ instantly. Latencies are introduced for multiple reasons: as mentioned certain storage backends require
+ time-based polling, in other cases wake-ups are optimized by coalescing events, and the OS introduces
+ additional IO/CPU scheduling latencies.</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 a negative
+ errno-style error code, or one of <constant>SD_JOURNAL_NOP</constant>, <constant>SD_JOURNAL_APPEND</constant> or
+ <constant>SD_JOURNAL_INVALIDATE</constant> on success:</para>
+
+ <itemizedlist>
+ <listitem><para>If <constant>SD_JOURNAL_NOP</constant> is returned, the journal did not change since the last
+ invocation.</para></listitem>
+
+ <listitem><para>If <constant>SD_JOURNAL_APPEND</constant> is returned, new entries have been appended to the end
+ of the journal. In this case it is sufficient to simply continue reading at the previous end location of the
+ journal, to read the newly added entries.</para></listitem>
+
+ <listitem><para>If <constant>SD_JOURNAL_INVALIDATE</constant>, journal files were added to or removed from the
+ set of journal files watched (e.g. due to rotation or vacuuming), and thus entries might have appeared or
+ disappeared at arbitrary places in the log stream, possibly before or after the previous end of the log
+ stream. If <constant>SD_JOURNAL_INVALIDATE</constant> is returned, live-view UIs that want to reflect on screen
+ the precise state of the log data on disk should probably refresh their entire display (relative to the cursor of
+ the log entry on the top of the screen). Programs only interested in a strictly sequential stream of log data may
+ treat <constant>SD_JOURNAL_INVALIDATE</constant> the same way as <constant>SD_JOURNAL_APPEND</constant>, thus
+ ignoring any changes to the log view earlier than the old end of the log stream.</para></listitem>
+ </itemizedlist>
+ </refsect1>
+
+ <refsect1>
+ <title>Signal safety</title>
+
+ <para>In general, <function>sd_journal_get_fd()</function>, <function>sd_journal_get_events()</function>, and
+ <function>sd_journal_get_timeout()</function> are <emphasis>not</emphasis> "async signal safe" in the meaning of
+ <citerefentry
+ project='man-pages'><refentrytitle>signal-safety</refentrytitle><manvolnum>7</manvolnum></citerefentry>.
+ Nevertheless, only the first call to any of those three functions performs unsafe operations, so subsequent calls
+ <emphasis>are</emphasis> safe.</para>
+
+ <para><function>sd_journal_process()</function> and <function>sd_journal_wait()</function> are not
+ safe. <function>sd_journal_reliable_fd()</function> is safe.</para>
+ </refsect1>
+
+ <refsect1>
+ <title>Notes</title>
+
+ <xi:include href="threads-aware.xml" xpointer="strict"/>
+
+ <xi:include href="libsystemd-pkgconfig.xml" xpointer="pkgconfig-text"/>
+ </refsect1>
+
+ <refsect1>
+ <title>Examples</title>
+
+ <para>Iterating through the journal, in a live view tracking all
+ changes:</para>
+
+ <programlisting><xi:include href="journal-iterate-wait.c" parse="text" /></programlisting>
+
+ <para>Waiting with <function>poll()</function> (this
+ example lacks all error checking for the sake of
+ simplicity):</para>
+
+ <programlisting><xi:include href="journal-iterate-poll.c" parse="text" /></programlisting>
+ </refsect1>
+
+ <refsect1>
+ <title>See Also</title>
+
+ <para>
+ <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
+ <citerefentry><refentrytitle>sd-journal</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+ <citerefentry><refentrytitle>sd_journal_open</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+ <citerefentry><refentrytitle>sd_journal_next</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+ <citerefentry><refentrytitle>poll</refentrytitle><manvolnum>2</manvolnum></citerefentry>,
+ <citerefentry><refentrytitle>clock_gettime</refentrytitle><manvolnum>2</manvolnum></citerefentry>
+ </para>
+ </refsect1>
+
+</refentry>