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