diff options
Diffstat (limited to 'man/sd_journal_get_fd.xml')
| -rw-r--r-- | man/sd_journal_get_fd.xml | 259 |
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 <systemd/sd-journal.h></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, &t); +if (t == (uint64_t) -1) + msec = -1; +else { + struct timespec ts; + uint64_t n; + clock_gettime(CLOCK_MONOTONIC, &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> |