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