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">
  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>Notes</title>
 235
 236     <para>The <function>sd_journal_get_fd()</function>,
 237     <function>sd_journal_get_events()</function>,
 238     <function>sd_journal_reliable_fd()</function>,
 239     <function>sd_journal_process()</function> and
 240     <function>sd_journal_wait()</function> interfaces are available as
 241     a shared library, which can be compiled and linked to with the
 242     <constant>libsystemd</constant> <citerefentry project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 243     file.</para>
 244   </refsect1>
 245
 246   <refsect1>
 247     <title>Examples</title>
 248
 249     <para>Iterating through the journal, in a live view tracking all
 250     changes:</para>
 251
 252     <programlisting>#include &lt;stdio.h&gt;
 253 #include &lt;string.h&gt;
 254 #include &lt;systemd/sd-journal.h&gt;
 255
 256 int main(int argc, char *argv[]) {
 257   int r;
 258   sd_journal *j;
 259   r = sd_journal_open(&amp;j, SD_JOURNAL_LOCAL_ONLY);
 260   if (r &lt; 0) {
 261     fprintf(stderr, "Failed to open journal: %s\n", strerror(-r));
 262     return 1;
 263   }
 264   for (;;)  {
 265     const void *d;
 266     size_t l;
 267     r = sd_journal_next(j);
 268     if (r &lt; 0) {
 269       fprintf(stderr, "Failed to iterate to next entry: %s\n", strerror(-r));
 270       break;
 271     }
 272     if (r == 0) {
 273       /* Reached the end, let's wait for changes, and try again */
 274       r = sd_journal_wait(j, (uint64_t) -1);
 275       if (r &lt; 0) {
 276         fprintf(stderr, "Failed to wait for changes: %s\n", strerror(-r));
 277         break;
 278       }
 279       continue;
 280     }
 281     r = sd_journal_get_data(j, "MESSAGE", &amp;d, &amp;l);
 282     if (r &lt; 0) {
 283       fprintf(stderr, "Failed to read message field: %s\n", strerror(-r));
 284       continue;
 285     }
 286     printf("%.*s\n", (int) l, (const char*) d);
 287   }
 288   sd_journal_close(j);
 289   return 0;
 290 }</programlisting>
 291
 292     <para>Waiting with <function>poll()</function> (this
 293     example lacks all error checking for the sake of
 294     simplicity):</para>
 295
 296     <programlisting>#include &lt;poll.h&gt;
 297 #include &lt;systemd/sd-journal.h&gt;
 298
 299 int wait_for_changes(sd_journal *j) {
 300   struct pollfd pollfd;
 301   int msec;
 302
 303   sd_journal_get_timeout(m, &amp;t);
 304   if (t == (uint64_t) -1)
 305     msec = -1;
 306   else {
 307     struct timespec ts;
 308     uint64_t n;
 309     clock_gettime(CLOCK_MONOTONIC, &amp;ts);
 310     n = (uint64_t) ts.tv_sec * 1000000 + ts.tv_nsec / 1000;
 311     msec = t > n ? (int) ((t - n + 999) / 1000) : 0;
 312   }
 313
 314   pollfd.fd = sd_journal_get_fd(j);
 315   pollfd.events = sd_journal_get_events(j);
 316   poll(&amp;pollfd, 1, msec);
 317   return sd_journal_process(j);
 318 }</programlisting>
 319   </refsect1>
 320
 321   <refsect1>
 322     <title>See Also</title>
 323
 324     <para>
 325       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 326       <citerefentry><refentrytitle>sd-journal</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 327       <citerefentry><refentrytitle>sd_journal_open</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 328       <citerefentry><refentrytitle>sd_journal_next</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 329       <citerefentry><refentrytitle>poll</refentrytitle><manvolnum>2</manvolnum></citerefentry>,
 330       <citerefentry><refentrytitle>clock_gettime</refentrytitle><manvolnum>2</manvolnum></citerefentry>
 331     </para>
 332   </refsect1>
 333
 334 </refentry>