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