man/sd_journal_get_fd.xml

   1 <?xml version='1.0'?> <!--*-nxml-*-->
   2 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
   3   "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
   4 <!-- SPDX-License-Identifier: LGPL-2.1+ -->
   5
   6 <refentry id="sd_journal_get_fd" xmlns:xi="http://www.w3.org/2001/XInclude">
   7
   8   <refentryinfo>
   9     <title>sd_journal_get_fd</title>
  10     <productname>systemd</productname>
  11   </refentryinfo>
  12
  13   <refmeta>
  14     <refentrytitle>sd_journal_get_fd</refentrytitle>
  15     <manvolnum>3</manvolnum>
  16   </refmeta>
  17
  18   <refnamediv>
  19     <refname>sd_journal_get_fd</refname>
  20     <refname>sd_journal_get_events</refname>
  21     <refname>sd_journal_get_timeout</refname>
  22     <refname>sd_journal_process</refname>
  23     <refname>sd_journal_wait</refname>
  24     <refname>sd_journal_reliable_fd</refname>
  25     <refname>SD_JOURNAL_NOP</refname>
  26     <refname>SD_JOURNAL_APPEND</refname>
  27     <refname>SD_JOURNAL_INVALIDATE</refname>
  28     <refpurpose>Journal change notification
  29     interface</refpurpose>
  30   </refnamediv>
  31
  32   <refsynopsisdiv>
  33     <funcsynopsis>
  34       <funcsynopsisinfo>#include &lt;systemd/sd-journal.h&gt;</funcsynopsisinfo>
  35
  36       <funcprototype>
  37         <funcdef>int <function>sd_journal_get_fd</function></funcdef>
  38         <paramdef>sd_journal *<parameter>j</parameter></paramdef>
  39       </funcprototype>
  40
  41       <funcprototype>
  42         <funcdef>int <function>sd_journal_get_events</function></funcdef>
  43         <paramdef>sd_journal *<parameter>j</parameter></paramdef>
  44       </funcprototype>
  45
  46       <funcprototype>
  47         <funcdef>int <function>sd_journal_get_timeout</function></funcdef>
  48         <paramdef>sd_journal *<parameter>j</parameter></paramdef>
  49         <paramdef>uint64_t *<parameter>timeout_usec</parameter></paramdef>
  50       </funcprototype>
  51
  52       <funcprototype>
  53         <funcdef>int <function>sd_journal_process</function></funcdef>
  54         <paramdef>sd_journal *<parameter>j</parameter></paramdef>
  55       </funcprototype>
  56
  57       <funcprototype>
  58         <funcdef>int <function>sd_journal_wait</function></funcdef>
  59         <paramdef>sd_journal *<parameter>j</parameter></paramdef>
  60         <paramdef>uint64_t <parameter>timeout_usec</parameter></paramdef>
  61       </funcprototype>
  62
  63       <funcprototype>
  64         <funcdef>int <function>sd_journal_reliable_fd</function></funcdef>
  65         <paramdef>sd_journal *<parameter>j</parameter></paramdef>
  66       </funcprototype>
  67
  68     </funcsynopsis>
  69   </refsynopsisdiv>
  70
  71   <refsect1>
  72     <title>Description</title>
  73
  74     <para><function>sd_journal_get_fd()</function> returns a file
  75     descriptor that may be asynchronously polled in an external event
  76     loop and is signaled as soon as the journal changes, because new
  77     entries or files were added, rotation took place, or files have
  78     been deleted, and similar. The file descriptor is suitable for
  79     usage in
  80     <citerefentry><refentrytitle>poll</refentrytitle><manvolnum>2</manvolnum></citerefentry>.
  81     Use <function>sd_journal_get_events()</function> for an events
  82     mask to watch for. The call takes one argument: the journal
  83     context object. Note that not all file systems are capable of
  84     generating the necessary events for wakeups from this file
  85     descriptor for changes to be noticed immediately. In particular
  86     network files systems do not generate suitable file change events
  87     in all cases. Cases like this can be detected with
  88     <function>sd_journal_reliable_fd()</function>, below.
  89     <function>sd_journal_get_timeout()</function> will ensure in these
  90     cases that wake-ups happen frequently enough for changes to be
  91     noticed, although with a certain latency.</para>
  92
  93     <para><function>sd_journal_get_events()</function> will return the
  94     <function>poll()</function> mask to wait for. This function will
  95     return a combination of <constant>POLLIN</constant> and
  96     <constant>POLLOUT</constant> and similar to fill into the
  97     <literal>.events</literal> field of <varname>struct
  98     pollfd</varname>.</para>
  99
 100     <para><function>sd_journal_get_timeout()</function> will return a
 101     timeout value for usage in <function>poll()</function>. This
 102     returns a value in microseconds since the epoch of
 103     <constant>CLOCK_MONOTONIC</constant> for timing out
 104     <function>poll()</function> in <varname>timeout_usec</varname>.
 105     See
 106     <citerefentry><refentrytitle>clock_gettime</refentrytitle><manvolnum>2</manvolnum></citerefentry>
 107     for details about <constant>CLOCK_MONOTONIC</constant>. If there
 108     is no timeout to wait for, this will fill in <constant>(uint64_t)
 109     -1</constant> instead. Note that <function>poll()</function> takes
 110     a relative timeout in milliseconds rather than an absolute timeout
 111     in microseconds. To convert the absolute 'us' timeout into
 112     relative 'ms', use code like the following:</para>
 113
 114     <programlisting>uint64_t t;
 115 int msec;
 116 sd_journal_get_timeout(m, &amp;t);
 117 if (t == (uint64_t) -1)
 118   msec = -1;
 119 else {
 120   struct timespec ts;
 121   uint64_t n;
 122   clock_gettime(CLOCK_MONOTONIC, &amp;ts);
 123   n = (uint64_t) ts.tv_sec * 1000000 + ts.tv_nsec / 1000;
 124   msec = t > n ? (int) ((t - n + 999) / 1000) : 0;
 125 }</programlisting>
 126
 127     <para>The code above does not do any error checking for brevity's
 128     sake. The calculated <varname>msec</varname> integer can be passed
 129     directly as <function>poll()</function>'s timeout
 130     parameter.</para>
 131
 132     <para>After each <function>poll()</function> wake-up
 133     <function>sd_journal_process()</function> needs to be called to
 134     process events. This call will also indicate what kind of change
 135     has been detected (see below; note that spurious wake-ups are
 136     possible).</para>
 137
 138     <para>A synchronous alternative for using
 139     <function>sd_journal_get_fd()</function>,
 140     <function>sd_journal_get_events()</function>,
 141     <function>sd_journal_get_timeout()</function> and
 142     <function>sd_journal_process()</function> is
 143     <function>sd_journal_wait()</function>. It will synchronously wait
 144     until the journal gets changed. The maximum time this call sleeps
 145     may be controlled with the <parameter>timeout_usec</parameter>
 146     parameter. Pass <constant>(uint64_t) -1</constant> to wait
 147     indefinitely. Internally this call simply combines
 148     <function>sd_journal_get_fd()</function>,
 149     <function>sd_journal_get_events()</function>,
 150     <function>sd_journal_get_timeout()</function>,
 151     <function>poll()</function> and
 152     <function>sd_journal_process()</function> into one.</para>
 153
 154     <para><function>sd_journal_reliable_fd()</function> may be used to
 155     check whether the wakeup events from the file descriptor returned
 156     by <function>sd_journal_get_fd()</function> are known to be
 157     immediately triggered. On certain file systems where file change
 158     events from the OS are not available (such as NFS) changes need to
 159     be polled for repeatedly, and hence are detected only with a
 160     certain latency. This call will return a positive value if the
 161     journal changes are detected immediately and zero when they need
 162     to be polled for and hence might be noticed only with a certain
 163     latency. Note that there is usually no need to invoke this function
 164     directly as <function>sd_journal_get_timeout()</function> on these
 165     file systems will ask for timeouts explicitly anyway.</para>
 166   </refsect1>
 167
 168   <refsect1>
 169     <title>Return Value</title>
 170
 171     <para><function>sd_journal_get_fd()</function> returns a valid
 172     file descriptor on success or a negative errno-style error
 173     code.</para>
 174
 175     <para><function>sd_journal_get_events()</function> returns a
 176     combination of <constant>POLLIN</constant>,
 177     <constant>POLLOUT</constant> and suchlike on success or a negative
 178     errno-style error code.</para>
 179
 180     <para><function>sd_journal_reliable_fd()</function> returns a
 181     positive integer if the file descriptor returned by
 182     <function>sd_journal_get_fd()</function> will generate wake-ups
 183     immediately for all journal changes. Returns 0 if there might be a
 184     latency involved.</para>
 185
 186     <para><function>sd_journal_process()</function> and <function>sd_journal_wait()</function> return a negative
 187     errno-style error code, or one of <constant>SD_JOURNAL_NOP</constant>, <constant>SD_JOURNAL_APPEND</constant> or
 188     <constant>SD_JOURNAL_INVALIDATE</constant> on success:</para>
 189
 190     <itemizedlist>
 191       <listitem><para>If <constant>SD_JOURNAL_NOP</constant> is returned, the journal did not change since the last
 192       invocation.</para></listitem>
 193
 194       <listitem><para>If <constant>SD_JOURNAL_APPEND</constant> is returned, new entries have been appended to the end
 195       of the journal. In this case it is sufficient to simply continue reading at the previous end location of the
 196       journal, to read the newly added entries.</para></listitem>
 197
 198       <listitem><para>If <constant>SD_JOURNAL_INVALIDATE</constant>, journal files were added to or removed from the
 199       set of journal files watched (e.g. due to rotation or vacuuming), and thus entries might have appeared or
 200       disappeared at arbitrary places in the log stream, possibly before or after the previous end of the log
 201       stream. If <constant>SD_JOURNAL_INVALIDATE</constant> is returned, live-view UIs that want to reflect on screen
 202       the precise state of the log data on disk should probably refresh their entire display (relative to the cursor of
 203       the log entry on the top of the screen). Programs only interested in a strictly sequential stream of log data may
 204       treat <constant>SD_JOURNAL_INVALIDATE</constant> the same way as <constant>SD_JOURNAL_APPEND</constant>, thus
 205       ignoring any changes to the log view earlier than the old end of the log stream.</para></listitem>
 206     </itemizedlist>
 207   </refsect1>
 208
 209   <refsect1>
 210     <title>Signal safety</title>
 211
 212     <para>In general, <function>sd_journal_get_fd()</function>, <function>sd_journal_get_events()</function>, and
 213     <function>sd_journal_get_timeout()</function> are <emphasis>not</emphasis> "async signal safe" in the meaning of
 214     <citerefentry
 215     project='man-pages'><refentrytitle>signal-safety</refentrytitle><manvolnum>7</manvolnum></citerefentry>.
 216     Nevertheless, only the first call to any of those three functions performs unsafe operations, so subsequent calls
 217     <emphasis>are</emphasis> safe.</para>
 218
 219     <para><function>sd_journal_process()</function> and <function>sd_journal_wait()</function> are not
 220     safe. <function>sd_journal_reliable_fd()</function> is safe.</para>
 221   </refsect1>
 222
 223   <refsect1>
 224     <title>Notes</title>
 225
 226     <xi:include href="threads-aware.xml" xpointer="strict"/>
 227
 228     <xi:include href="libsystemd-pkgconfig.xml" xpointer="pkgconfig-text"/>
 229   </refsect1>
 230
 231   <refsect1>
 232     <title>Examples</title>
 233
 234     <para>Iterating through the journal, in a live view tracking all
 235     changes:</para>
 236
 237     <programlisting><xi:include href="journal-iterate-wait.c" parse="text" /></programlisting>
 238
 239     <para>Waiting with <function>poll()</function> (this
 240     example lacks all error checking for the sake of
 241     simplicity):</para>
 242
 243     <programlisting><xi:include href="journal-iterate-poll.c" parse="text" /></programlisting>
 244   </refsect1>
 245
 246   <refsect1>
 247     <title>See Also</title>
 248
 249     <para>
 250       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 251       <citerefentry><refentrytitle>sd-journal</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 252       <citerefentry><refentrytitle>sd_journal_open</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 253       <citerefentry><refentrytitle>sd_journal_next</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 254       <citerefentry><refentrytitle>poll</refentrytitle><manvolnum>2</manvolnum></citerefentry>,
 255       <citerefentry><refentrytitle>clock_gettime</refentrytitle><manvolnum>2</manvolnum></citerefentry>
 256     </para>
 257   </refsect1>
 258
 259 </refentry>