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