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
 102                 a file descriptor that may be asynchronously polled in
 103                 an external event loop and is signaled as soon as the
 104                 journal changes, because new entries or files were
 105                 added, rotation took place, or files have been
 106                 deleted, and similar. The file descriptor is suitable
 107                 for usage in
 108                 <citerefentry><refentrytitle>poll</refentrytitle><manvolnum>2</manvolnum></citerefentry>. Use
 109                 <function>sd_journal_get_events()</function> for an
 110                 events mask to watch for. The call takes one argument:
 111                 the journal context object. Note that not all file
 112                 systems are capable of generating the necessary events
 113                 for wakeups from this file descriptor for changes to
 114                 be noticed immediately. In particular network files
 115                 systems do not generate suitable file change events in
 116                 all cases. Cases like this can be detected with
 117                 <function>sd_journal_reliable_fd()</function>,
 118                 below. <function>sd_journal_get_timeout()</function>
 119                 will ensure in these cases that wake-ups happen
 120                 frequently enough for changes to be noticed, although
 121                 with a certain latency.</para>
 122
 123                 <para><function>sd_journal_get_events()</function>
 124                 will return the <function>poll()</function> mask to
 125                 wait for. This function will return a combination of
 126                 <literal>POLLIN</literal> and
 127                 <literal>POLLOUT</literal> and similar to fill into
 128                 the <literal>.events</literal> field of
 129                 <literal>struct pollfd</literal>.</para>
 130
 131                 <para><function>sd_journal_get_timeout()</function>
 132                 will return a timeout value for usage in <function>poll()</function>. This returns a value in microseconds since the epoch of CLOCK_MONOTONIC for timing out <function>poll()</function> in <literal>timeout_usec</literal>. See
 133                 <citerefentry><refentrytitle>clock_gettime</refentrytitle><manvolnum>2</manvolnum></citerefentry>
 134                 for details about
 135                 <literal>CLOCK_MONOTONIC</literal>. If there's no
 136                 timeout to wait for this will fill in
 137                 <literal>(uint64_t) -1</literal> instead. Note that
 138                 <function>poll()</function> takes a relative timeout
 139                 in milliseconds rather than an absolute timeout in
 140                 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_getttime(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
 157                 for brevity's sake. The calculated <literal>msec</literal>
 158                 integer can be passed directly as
 159                 <function>poll()</function>'s timeout
 160                 parameter.</para>
 161
 162                 <para>After each <function>poll()</function> wake-up
 163                 <function>sd_journal_process()</function> needs to be
 164                 called to process events. This call will also indicate
 165                 what kind of change has been detected (see below; note
 166                 that spurious wake-ups are possible).</para>
 167
 168                 <para>A synchronous alternative for using
 169                 <function>sd_journal_get_fd()</function>,
 170                 <function>sd_journal_get_events()</function>,
 171                 <function>sd_journal_get_timeout()</function> and
 172                 <function>sd_journal_process()</function> is
 173                 <function>sd_journal_wait()</function>. It will
 174                 synchronously wait until the journal gets changed. The
 175                 maximum time this call sleeps may be controlled with
 176                 the <parameter>timeout_usec</parameter>
 177                 parameter. Pass <literal>(uint64_t) -1</literal> to
 178                 wait indefinitely. Internally this call simply
 179                 combines <function>sd_journal_get_fd()</function>,
 180                 <function>sd_journal_get_events()</function>,
 181                 <function>sd_journal_get_timeout()</function>,
 182                 <function>poll()</function> and
 183                 <function>sd_journal_process()</function> into
 184                 one.</para>
 185
 186                 <para><function>sd_journal_reliable_fd()</function>
 187                 may be used to check whether the wakeup events from
 188                 the file descriptor returned by
 189                 <function>sd_journal_get_fd()</function> are known to
 190                 be immediately triggered. On certain file systems
 191                 where file change events from the OS are not available
 192                 (such as NFS) changes need to be polled for
 193                 repeatedly, and hence are detected only with a certain
 194                 latency. This call will return a positive value if the
 195                 journal changes are detected immediately and zero when
 196                 they need to be polled for and hence might be noticed
 197                 only with a certain latency. Note that there's usually
 198                 no need to invoke this function directly as
 199                 <function>sd_journal_get_timeout()</function> on these
 200                 file systems will ask for timeouts explicitly
 201                 anyway.</para>
 202         </refsect1>
 203
 204         <refsect1>
 205                 <title>Return Value</title>
 206
 207                 <para><function>sd_journal_get_fd()</function> returns
 208                 a valid file descriptor on success or a negative
 209                 errno-style error code.</para>
 210
 211                 <para><function>sd_journal_get_events()</function>
 212                 returns a combination of <literal>POLLIN</literal>,
 213                 <literal>POLLOUT</literal> and suchlike on success or
 214                 a negative errno-style error code.</para>
 215
 216                 <para><function>sd_journal_reliable_fd()</function>
 217                 returns a positive integer if the file descriptor
 218                 returned by <function>sd_journal_get_fd()</function>
 219                 will generate wake-ups immediately for all journal
 220                 changes. Returns 0 if there might be a latency
 221                 involved.</para>
 222
 223                 <para><function>sd_journal_process()</function> and
 224                 <function>sd_journal_wait()</function> return one of
 225                 <literal>SD_JOURNAL_NOP</literal>,
 226                 <literal>SD_JOURNAL_APPEND</literal> or
 227                 <literal>SD_JOURNAL_INVALIDATE</literal> on success or
 228                 a negative errno-style error code. If
 229                 <literal>SD_JOURNAL_NOP</literal> is returned the
 230                 journal didn't change since the last invocation. If
 231                 <literal>SD_JOURNAL_APPEND</literal> is returned new
 232                 entries have been appended to the end of the
 233                 journal. If <literal>SD_JOURNAL_INVALIDATE</literal>
 234                 journal files were added or removed (possibly due to
 235                 rotation). In the latter event live-view UIs should
 236                 probably refresh their entire display while in the
 237                 case of <literal>SD_JOURNAL_APPEND</literal> it is
 238                 sufficient to simply continue reading at the previous
 239                 end of the journal.</para>
 240         </refsect1>
 241
 242         <refsect1>
 243                 <title>Notes</title>
 244
 245                 <para>The <function>sd_journal_get_fd()</function>,
 246                 <function>sd_journal_get_events()</function>,
 247                 <function>sd_journal_reliable_fd()</function>,
 248                 <function>sd_journal_process()</function> and
 249                 <function>sd_journal_wait()</function> interfaces are
 250                 available as shared library, which can be compiled and
 251                 linked to with the
 252                 <literal>libsystemd-journal</literal>
 253                 <citerefentry><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 254                 file.</para>
 255         </refsect1>
 256
 257         <refsect1>
 258                 <title>Examples</title>
 259
 260                 <para>Iterating through the journal, in a live view tracking all changes:</para>
 261
 262                 <programlisting>#include &lt;stdio.h&gt;
 263 #include &lt;string.h&gt;
 264 #include &lt;systemd/sd-journal.h&gt;
 265
 266 int main(int argc, char *argv[]) {
 267         int r;
 268         sd_journal *j;
 269         r = sd_journal_open(&amp;j, SD_JOURNAL_LOCAL_ONLY);
 270         if (r &lt; 0) {
 271                 fprintf(stderr, "Failed to open journal: %s\n", strerror(-r));
 272                 return 1;
 273         }
 274         for (;;)  {
 275                 const void *d;
 276                 size_t l;
 277                 r = sd_journal_next(j);
 278                 if (r &lt; 0) {
 279                         fprintf(stderr, "Failed to iterate to next entry: %s\n", strerror(-r));
 280                         break;
 281                 }
 282                 if (r == 0) {
 283                         /* Reached the end, let's wait for changes, and try again */
 284                         r = sd_journal_wait(j, (uint64_t) -1);
 285                         if (r &lt; 0) {
 286                                 fprintf(stderr, "Failed to wait for changes: %s\n", strerror(-r));
 287                                 break;
 288                         }
 289                         continue;
 290                 }
 291                 r = sd_journal_get_data(j, "MESSAGE", &amp;d, &amp;l);
 292                 if (r &lt; 0) {
 293                         fprintf(stderr, "Failed to read message field: %s\n", strerror(-r));
 294                         continue;
 295                 }
 296                 printf("%.*s\n", (int) l, (const char*) d);
 297         }
 298         sd_journal_close(j);
 299         return 0;
 300 }</programlisting>
 301
 302                 <para>Waiting with <function>poll()</function> (this
 303                 example lacks all error checking for the sake of
 304                 simplicity):</para>
 305
 306                 <programlisting>#include &lt;sys/poll.h&gt;
 307 #include &lt;systemd/sd-journal.h&gt;
 308
 309 int wait_for_changes(sd_journal *j) {
 310         struct pollfd pollfd;
 311         int msec;
 312
 313         sd_journal_get_timeout(m, &amp;t);
 314         if (t == (uint64_t) -1)
 315                 msec = -1;
 316         else {
 317                 struct timespec ts;
 318                 uint64_t n;
 319                 clock_getttime(CLOCK_MONOTONIC, &amp;ts);
 320                 n = (uint64_t) ts.tv_sec * 1000000 + ts.tv_nsec / 1000;
 321                 msec = t > n ? (int) ((t - n + 999) / 1000) : 0;
 322         }
 323
 324         pollfd.fd = sd_journal_get_fd(j);
 325         pollfd.events = sd_journal_get_events(j);
 326         poll(&amp;pollfd, 1, msec);
 327         return sd_journal_process(j);
 328 }
 329                 </programlisting>
 330         </refsect1>
 331
 332         <refsect1>
 333                 <title>See Also</title>
 334
 335                 <para>
 336                         <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 337                         <citerefentry><refentrytitle>sd-journal</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 338                         <citerefentry><refentrytitle>sd_journal_open</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 339                         <citerefentry><refentrytitle>sd_journal_next</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 340                         <citerefentry><refentrytitle>poll</refentrytitle><manvolnum>2</manvolnum></citerefentry>,
 341                         <citerefentry><refentrytitle>clock_gettime</refentrytitle><manvolnum>2</manvolnum></citerefentry>
 342                 </para>
 343         </refsect1>
 344
 345 </refentry>