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_process</refname>
  48                 <refname>sd_journal_wait</refname>
  49                 <refpurpose>Journal change notification
  50                 interface</refpurpose>
  51         </refnamediv>
  52
  53         <refsynopsisdiv>
  54                 <funcsynopsis>
  55                         <funcsynopsisinfo>#include &lt;systemd/sd-journal.h&gt;</funcsynopsisinfo>
  56
  57                         <funcprototype>
  58                                 <funcdef>int <function>sd_journal_get_fd</function></funcdef>
  59                                 <paramdef>sd_journal* <parameter>j</parameter></paramdef>
  60                         </funcprototype>
  61
  62                         <funcprototype>
  63                                 <funcdef>int <function>sd_journal_process</function></funcdef>
  64                                 <paramdef>sd_journal* <parameter>j</parameter></paramdef>
  65                         </funcprototype>
  66
  67                         <funcprototype>
  68                                 <funcdef>int <function>sd_journal_wait</function></funcdef>
  69                                 <paramdef>sd_journal* <parameter>j</parameter></paramdef>
  70                                 <paramdef>uint64_t <parameter>timeout_usec</parameter></paramdef>
  71                         </funcprototype>
  72
  73                 </funcsynopsis>
  74         </refsynopsisdiv>
  75
  76         <refsect1>
  77                 <title>Description</title>
  78
  79                 <para><function>sd_journal_get_fd()</function> returns
  80                 a file descriptor that may be asynchronously polled in
  81                 an external event loop and is signalled readable as
  82                 soon as the journal changes, for example because new
  83                 entries were added. The file descriptor is suitable
  84                 for usage in
  85                 <citerefentry><refentrytitle>poll</refentrytitle><manvolnum>2</manvolnum></citerefentry>
  86                 where it will yield POLLIN on all changes. The call
  87                 takes one argument: the journal context object.</para>
  88
  89                 <para>After each POLLIN wake-up
  90                 <function>sd_journal_process()</function> needs to be
  91                 called to process events and reset the readable state
  92                 of the file descriptor. This call will also indicate
  93                 what kind of change has been detected (see below; note
  94                 that spurious wake-ups are possible).</para>
  95
  96                 <para>A synchronous alternative for using
  97                 <function>sd_journal_get_fd()</function> and
  98                 <function>sd_journal_process()</function> is
  99                 <function>sd_journal_wait()</function>. It will
 100                 synchronously wait until the journal gets changed up
 101                 to a certain time-out as specified in its second
 102                 argument. Pass <literal>(uint64_t) -1</literal> to
 103                 wait indefinitely. Internally this call simply
 104                 combines <function>sd_journal_get_fd()</function>,
 105                 <function>poll()</function> and
 106                 <function>sd_journal_process()</function> into
 107                 one.</para>
 108
 109         </refsect1>
 110
 111         <refsect1>
 112                 <title>Return Value</title>
 113
 114                 <para><function>sd_journal_get_fd()</function> returns a valid file descriptor on success or a negative errno-style error
 115                 code.</para>
 116
 117                 <para><function>sd_journal_process()</function> and
 118                 <function>sd_journal_wait()</function> return one of
 119                 <literal>SD_JOURNAL_NOP</literal>,
 120                 <literal>SD_JOURNAL_APPEND</literal> or
 121                 <literal>SD_JOURNAL_INVALIDATE</literal> on success or
 122                 a negative errno-style error code. If
 123                 <literal>SD_JOURNAL_NOP</literal> is returned the
 124                 journal didn't change since the last invocation. If
 125                 <literal>SD_JOURNAL_APPEND</literal> is returned new
 126                 entries have been appended to the end of the
 127                 journal. If <literal>SD_JOURNAL_INVALIDATE</literal>
 128                 journal files were added or removed (possibly due to
 129                 rotation). In the latter event live-view UIs should
 130                 probably refresh their entire display while in the
 131                 case of <literal>SD_JOURNAL_APPEND</literal> it is
 132                 sufficient to simply continue reading at the previous
 133                 end of the journal.</para>
 134         </refsect1>
 135
 136         <refsect1>
 137                 <title>Notes</title>
 138
 139                 <para>The <function>sd_journal_get_fd()</function>,
 140                 <function>sd_journal_process()</function> and
 141                 <function>sd_journal_wait()</function> interfaces are
 142                 available as shared library, which can be compiled and
 143                 linked to with the
 144                 <literal>libsystemd-journal</literal>
 145                 <citerefentry><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 146                 file.</para>
 147         </refsect1>
 148
 149         <refsect1>
 150                 <title>See Also</title>
 151
 152                 <para>
 153                         <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 154                         <citerefentry><refentrytitle>sd-journal</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 155                         <citerefentry><refentrytitle>sd_journal_open</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 156                         <citerefentry><refentrytitle>sd_journal_next</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 157                 </para>
 158         </refsect1>
 159
 160 </refentry>