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