man/sd_journal_get_fd.xml

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