Adding upstream version 255.4.upstream/255.4

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 269 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..6e7e496
--- /dev/null
+++ b/man/sd_journal_get_fd.xml
@@ -0,0 +1,269 @@
+<?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>History</title>
+    <para><function>sd_journal_get_fd()</function>,
+    <function>sd_journal_process()</function>, and
+    <function>sd_journal_wait()</function> were added in version 187.</para>
+    <para><function>sd_journal_reliable_fd()</function> was added in version 196.</para>
+    <para><function>sd_journal_get_events()</function> and
+    <function>sd_journal_get_timeout()</function> were added in version 201.</para>
+  </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>