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_reliable_fd</refname>
  49                 <refname>sd_journal_process</refname>
  50                 <refname>sd_journal_wait</refname>
  51                 <refname>SD_JOURNAL_NOP</refname>
  52                 <refname>SD_JOURNAL_APPEND</refname>
  53                 <refname>SD_JOURNAL_INVALIDATE</refname>
  54                 <refpurpose>Journal change notification
  55                 interface</refpurpose>
  56         </refnamediv>
  57
  58         <refsynopsisdiv>
  59                 <funcsynopsis>
  60                         <funcsynopsisinfo>#include &lt;systemd/sd-journal.h&gt;</funcsynopsisinfo>
  61
  62                         <funcprototype>
  63                                 <funcdef>int <function>sd_journal_get_fd</function></funcdef>
  64                                 <paramdef>sd_journal* <parameter>j</parameter></paramdef>
  65                         </funcprototype>
  66
  67                         <funcprototype>
  68                                 <funcdef>int <function>sd_journal_get_events</function></funcdef>
  69                                 <paramdef>sd_journal* <parameter>j</parameter></paramdef>
  70                         </funcprototype>
  71
  72                         <funcprototype>
  73                                 <funcdef>int <function>sd_journal_reliable_fd</function></funcdef>
  74                                 <paramdef>sd_journal* <parameter>j</parameter></paramdef>
  75                         </funcprototype>
  76
  77                         <funcprototype>
  78                                 <funcdef>int <function>sd_journal_process</function></funcdef>
  79                                 <paramdef>sd_journal* <parameter>j</parameter></paramdef>
  80                         </funcprototype>
  81
  82                         <funcprototype>
  83                                 <funcdef>int <function>sd_journal_wait</function></funcdef>
  84                                 <paramdef>sd_journal* <parameter>j</parameter></paramdef>
  85                                 <paramdef>uint64_t <parameter>timeout_usec</parameter></paramdef>
  86                         </funcprototype>
  87
  88                 </funcsynopsis>
  89         </refsynopsisdiv>
  90
  91         <refsect1>
  92                 <title>Description</title>
  93
  94                 <para><function>sd_journal_get_fd()</function> returns
  95                 a file descriptor that may be asynchronously polled in
  96                 an external event loop and is signaled as soon as the
  97                 journal changes, because new entries or files were
  98                 added, rotation took place, or files have been
  99                 deleted, and similar. The file descriptor is suitable
 100                 for usage in
 101                 <citerefentry><refentrytitle>poll</refentrytitle><manvolnum>2</manvolnum></citerefentry>. Use
 102                 <function>sd_journal_get_events()</function> for an
 103                 events mask to watch for. The call takes one argument:
 104                 the journal context object. Note that not all file
 105                 systems are capable of generating the necessary events
 106                 for wakeups from this file descriptor to be enirely
 107                 reliable. In particular network files systems do not
 108                 generate suitable file change events in all cases. In
 109                 such a case an application should not rely alone on
 110                 wake-ups from this file descriptor but wake up and
 111                 recheck the journal in regular time intervals, for
 112                 example every 2s. To detect cases where this is
 113                 necessary, use
 114                 <function>sd_journal_reliable_fd()</function>,
 115                 below.</para>
 116
 117                 <para><function>sd_journal_get_events()</function>
 118                 will return the <function>poll()</function> mask to
 119                 wait for. This function will return a combination of
 120                 <literal>POLLIN</literal> and
 121                 <literal>POLLOUT</literal> and similar to fill into
 122                 the <literal>.events</literal> field of
 123                 <literal>struct pollfd</literal>.</para>
 124
 125                 <para><function>sd_journal_reliable_fd()</function>
 126                 may be used to check whether the wakeup events from
 127                 the file descriptor returned by
 128                 <function>sd_journal_get_fd</function> are sufficient
 129                 to track changes to the journal. If this call returns
 130                 0, it is necessary to regularly recheck for journal
 131                 changes (suggestion: every 2s). If this call returns a
 132                 positive integer this is not necessary, and wakeups
 133                 from the file descriptor returned by
 134                 <function>sd_journal_get_fd()</function> are
 135                 sufficient as only source for wake-ups.</para>
 136
 137                 <para>After each <function>poll()</function> wake-up
 138                 <function>sd_journal_process()</function> needs to be
 139                 called to process events. This call will also indicate
 140                 what kind of change has been detected (see below; note
 141                 that spurious wake-ups are possible).</para>
 142
 143                 <para>A synchronous alternative for using
 144                 <function>sd_journal_get_fd()</function>,
 145                 <function>sd_journal_get_events()</function>,
 146                 <function>sd_journal_reliable_fd()</function> and
 147                 <function>sd_journal_process()</function> is
 148                 <function>sd_journal_wait()</function>. It will
 149                 synchronously wait until the journal gets changed,
 150                 possibly using a 2s time-out if this is necessary (see
 151                 above). In either way the maximum time this call
 152                 sleeps may be controlled with the
 153                 <parameter>timeout_usec</parameter> parameter. Pass
 154                 <literal>(uint64_t) -1</literal> to wait
 155                 indefinitely. Internally this call simply combines
 156                 <function>sd_journal_get_fd()</function>,
 157                 <function>sd_journal_get_events()</function>,
 158                 <function>sd_journal_reliable_fd()</function>,
 159                 <function>poll()</function> and
 160                 <function>sd_journal_process()</function> into
 161                 one.</para>
 162         </refsect1>
 163
 164         <refsect1>
 165                 <title>Return Value</title>
 166
 167                 <para><function>sd_journal_get_fd()</function> returns
 168                 a valid file descriptor on success or a negative
 169                 errno-style error code.</para>
 170
 171                 <para><function>sd_journal_get_events()</function>
 172                 returns a combination of <literal>POLLIN</literal>,
 173                 <literal>POLLOUT</literal> and suchlike on success or
 174                 a negative errno-style error code.</para>
 175
 176                 <para><function>sd_journal_reliable_fd()</function>
 177                 returns a positive integer if the file descriptor
 178                 returned by <function>sd_journal_get_fd()</function>
 179                 is sufficient as sole wake-up source for journal
 180                 change events. Returns 0 if it is not sufficient and
 181                 the journal needs to be checked manually in regular
 182                 time intervals for changes. Returns a negative
 183                 errno-style error code on failure.</para>
 184
 185                 <para><function>sd_journal_process()</function> and
 186                 <function>sd_journal_wait()</function> return one of
 187                 <literal>SD_JOURNAL_NOP</literal>,
 188                 <literal>SD_JOURNAL_APPEND</literal> or
 189                 <literal>SD_JOURNAL_INVALIDATE</literal> on success or
 190                 a negative errno-style error code. If
 191                 <literal>SD_JOURNAL_NOP</literal> is returned the
 192                 journal didn't change since the last invocation. If
 193                 <literal>SD_JOURNAL_APPEND</literal> is returned new
 194                 entries have been appended to the end of the
 195                 journal. If <literal>SD_JOURNAL_INVALIDATE</literal>
 196                 journal files were added or removed (possibly due to
 197                 rotation). In the latter event live-view UIs should
 198                 probably refresh their entire display while in the
 199                 case of <literal>SD_JOURNAL_APPEND</literal> it is
 200                 sufficient to simply continue reading at the previous
 201                 end of the journal.</para>
 202         </refsect1>
 203
 204         <refsect1>
 205                 <title>Notes</title>
 206
 207                 <para>The <function>sd_journal_get_fd()</function>,
 208                 <function>sd_journal_get_events()</function>,
 209                 <function>sd_journal_reliable_fd()</function>,
 210                 <function>sd_journal_process()</function> and
 211                 <function>sd_journal_wait()</function> interfaces are
 212                 available as shared library, which can be compiled and
 213                 linked to with the
 214                 <literal>libsystemd-journal</literal>
 215                 <citerefentry><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 216                 file.</para>
 217         </refsect1>
 218
 219         <refsect1>
 220                 <title>Examples</title>
 221
 222                 <para>Iterating through the journal, in a live view tracking all changes:</para>
 223
 224                 <programlisting>#include &lt;stdio.h&gt;
 225 #include &lt;string.h&gt;
 226 #include &lt;systemd/sd-journal.h&gt;
 227
 228 int main(int argc, char *argv[]) {
 229         int r;
 230         sd_journal *j;
 231         r = sd_journal_open(&amp;j, SD_JOURNAL_LOCAL_ONLY);
 232         if (r &lt; 0) {
 233                 fprintf(stderr, "Failed to open journal: %s\n", strerror(-r));
 234                 return 1;
 235         }
 236         for (;;)  {
 237                 const void *d;
 238                 size_t l;
 239                 r = sd_journal_next(j);
 240                 if (r &lt; 0) {
 241                         fprintf(stderr, "Failed to iterate to next entry: %s\n", strerror(-r));
 242                         break;
 243                 }
 244                 if (r == 0) {
 245                         /* Reached the end, let's wait for changes, and try again */
 246                         r = sd_journal_wait(j, (uint64_t) -1);
 247                         if (r &lt; 0) {
 248                                 fprintf(stderr, "Failed to wait for changes: %s\n", strerror(-r));
 249                                 break;
 250                         }
 251                         continue;
 252                 }
 253                 r = sd_journal_get_data(j, "MESSAGE", &amp;d, &amp;l);
 254                 if (r &lt; 0) {
 255                         fprintf(stderr, "Failed to read message field: %s\n", strerror(-r));
 256                         continue;
 257                 }
 258                 printf("%.*s\n", (int) l, (const char*) d);
 259         }
 260         sd_journal_close(j);
 261         return 0;
 262 }</programlisting>
 263
 264                 <para>Waiting with <function>poll()</function> (this
 265                 example lacks all error checking for the sake of
 266                 simplicity):</para>
 267
 268                 <programlisting>#include &lt;sys/poll.h&gt;
 269 #include &lt;systemd/sd-journal.h&gt;
 270
 271 int wait_for_changes(sd_journal *j) {
 272         struct pollfd pollfd;
 273         pollfd.fd = sd_journal_get_fd(j);
 274         pollfd.events = sd_journal_get_events(j);
 275         poll(&amp;pollfd, 1, sd_journal_reliable_fd(j) &gt; 0 ? -1 : 2000);
 276         return sd_journal_process(j);
 277 }
 278                 </programlisting>
 279         </refsect1>
 280
 281         <refsect1>
 282                 <title>See Also</title>
 283
 284                 <para>
 285                         <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 286                         <citerefentry><refentrytitle>sd-journal</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 287                         <citerefentry><refentrytitle>sd_journal_open</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 288                         <citerefentry><refentrytitle>sd_journal_next</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 289                         <citerefentry><refentrytitle>poll</refentrytitle><manvolnum>2</manvolnum></citerefentry>
 290                 </para>
 291         </refsect1>
 292
 293 </refentry>