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
 203     <function>sd_journal_wait()</function> return one of
 204     <constant>SD_JOURNAL_NOP</constant>,
 205     <constant>SD_JOURNAL_APPEND</constant> or
 206     <constant>SD_JOURNAL_INVALIDATE</constant> on success or a
 207     negative errno-style error code. If
 208     <constant>SD_JOURNAL_NOP</constant> is returned, the journal did
 209     not change since the last invocation. If
 210     <constant>SD_JOURNAL_APPEND</constant> is returned, new entries
 211     have been appended to the end of the journal. If
 212     <constant>SD_JOURNAL_INVALIDATE</constant>, journal files were
 213     added or removed (possibly due to rotation). In the latter event,
 214     live-view UIs should probably refresh their entire display, while
 215     in the case of <constant>SD_JOURNAL_APPEND</constant>, it is
 216     sufficient to simply continue reading at the previous end of the
 217     journal.</para>
 218   </refsect1>
 219
 220   <refsect1>
 221     <title>Signal safety</title>
 222
 223     <para>In general, <function>sd_journal_get_fd()</function>, <function>sd_journal_get_events()</function>, and
 224     <function>sd_journal_get_timeout()</function> are <emphasis>not</emphasis> "async signal safe" in the meaning of
 225     <citerefentry
 226     project='man-pages'><refentrytitle>signal-safety</refentrytitle><manvolnum>7</manvolnum></citerefentry>.
 227     Nevertheless, only the first call to any of those three functions performs unsafe operations, so subsequent calls
 228     <emphasis>are</emphasis> safe.</para>
 229
 230     <para><function>sd_journal_process()</function> and <function>sd_journal_wait()</function> are not
 231     safe. <function>sd_journal_reliable_fd()</function> is safe.</para>
 232   </refsect1>
 233
 234   <refsect1>
 235     <title>Notes</title>
 236
 237     <para>The <function>sd_journal_get_fd()</function>,
 238     <function>sd_journal_get_events()</function>,
 239     <function>sd_journal_reliable_fd()</function>,
 240     <function>sd_journal_process()</function> and
 241     <function>sd_journal_wait()</function> interfaces are available as
 242     a shared library, which can be compiled and linked to with the
 243     <constant>libsystemd</constant> <citerefentry project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 244     file.</para>
 245   </refsect1>
 246
 247   <refsect1>
 248     <title>Examples</title>
 249
 250     <para>Iterating through the journal, in a live view tracking all
 251     changes:</para>
 252
 253     <programlisting><xi:include href="journal-iterate-wait.c" parse="text" /></programlisting>
 254
 255     <para>Waiting with <function>poll()</function> (this
 256     example lacks all error checking for the sake of
 257     simplicity):</para>
 258
 259     <programlisting><xi:include href="journal-iterate-poll.c" parse="text" /></programlisting>
 260   </refsect1>
 261
 262   <refsect1>
 263     <title>See Also</title>
 264
 265     <para>
 266       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 267       <citerefentry><refentrytitle>sd-journal</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 268       <citerefentry><refentrytitle>sd_journal_open</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 269       <citerefentry><refentrytitle>sd_journal_next</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 270       <citerefentry><refentrytitle>poll</refentrytitle><manvolnum>2</manvolnum></citerefentry>,
 271       <citerefentry><refentrytitle>clock_gettime</refentrytitle><manvolnum>2</manvolnum></citerefentry>
 272     </para>
 273   </refsect1>
 274
 275 </refentry>