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">
6 SPDX-License-Identifier: LGPL-2.1+
9 <refentry id=
"sd_journal_get_fd" xmlns:
xi=
"http://www.w3.org/2001/XInclude">
12 <title>sd_journal_get_fd
</title>
13 <productname>systemd
</productname>
17 <refentrytitle>sd_journal_get_fd
</refentrytitle>
18 <manvolnum>3</manvolnum>
22 <refname>sd_journal_get_fd
</refname>
23 <refname>sd_journal_get_events
</refname>
24 <refname>sd_journal_get_timeout
</refname>
25 <refname>sd_journal_process
</refname>
26 <refname>sd_journal_wait
</refname>
27 <refname>sd_journal_reliable_fd
</refname>
28 <refname>SD_JOURNAL_NOP
</refname>
29 <refname>SD_JOURNAL_APPEND
</refname>
30 <refname>SD_JOURNAL_INVALIDATE
</refname>
31 <refpurpose>Journal change notification
32 interface
</refpurpose>
37 <funcsynopsisinfo>#include
<systemd/sd-journal.h
></funcsynopsisinfo>
40 <funcdef>int
<function>sd_journal_get_fd
</function></funcdef>
41 <paramdef>sd_journal *
<parameter>j
</parameter></paramdef>
45 <funcdef>int
<function>sd_journal_get_events
</function></funcdef>
46 <paramdef>sd_journal *
<parameter>j
</parameter></paramdef>
50 <funcdef>int
<function>sd_journal_get_timeout
</function></funcdef>
51 <paramdef>sd_journal *
<parameter>j
</parameter></paramdef>
52 <paramdef>uint64_t *
<parameter>timeout_usec
</parameter></paramdef>
56 <funcdef>int
<function>sd_journal_process
</function></funcdef>
57 <paramdef>sd_journal *
<parameter>j
</parameter></paramdef>
61 <funcdef>int
<function>sd_journal_wait
</function></funcdef>
62 <paramdef>sd_journal *
<parameter>j
</parameter></paramdef>
63 <paramdef>uint64_t
<parameter>timeout_usec
</parameter></paramdef>
67 <funcdef>int
<function>sd_journal_reliable_fd
</function></funcdef>
68 <paramdef>sd_journal *
<parameter>j
</parameter></paramdef>
75 <title>Description
</title>
77 <para><function>sd_journal_get_fd()
</function> returns a file
78 descriptor that may be asynchronously polled in an external event
79 loop and is signaled as soon as the journal changes, because new
80 entries or files were added, rotation took place, or files have
81 been deleted, and similar. The file descriptor is suitable for
83 <citerefentry><refentrytitle>poll
</refentrytitle><manvolnum>2</manvolnum></citerefentry>.
84 Use
<function>sd_journal_get_events()
</function> for an events
85 mask to watch for. The call takes one argument: the journal
86 context object. Note that not all file systems are capable of
87 generating the necessary events for wakeups from this file
88 descriptor for changes to be noticed immediately. In particular
89 network files systems do not generate suitable file change events
90 in all cases. Cases like this can be detected with
91 <function>sd_journal_reliable_fd()
</function>, below.
92 <function>sd_journal_get_timeout()
</function> will ensure in these
93 cases that wake-ups happen frequently enough for changes to be
94 noticed, although with a certain latency.
</para>
96 <para><function>sd_journal_get_events()
</function> will return the
97 <function>poll()
</function> mask to wait for. This function will
98 return a combination of
<constant>POLLIN
</constant> and
99 <constant>POLLOUT
</constant> and similar to fill into the
100 <literal>.events
</literal> field of
<varname>struct
101 pollfd
</varname>.
</para>
103 <para><function>sd_journal_get_timeout()
</function> will return a
104 timeout value for usage in
<function>poll()
</function>. This
105 returns a value in microseconds since the epoch of
106 <constant>CLOCK_MONOTONIC
</constant> for timing out
107 <function>poll()
</function> in
<varname>timeout_usec
</varname>.
109 <citerefentry><refentrytitle>clock_gettime
</refentrytitle><manvolnum>2</manvolnum></citerefentry>
110 for details about
<constant>CLOCK_MONOTONIC
</constant>. If there
111 is no timeout to wait for, this will fill in
<constant>(uint64_t)
112 -
1</constant> instead. Note that
<function>poll()
</function> takes
113 a relative timeout in milliseconds rather than an absolute timeout
114 in microseconds. To convert the absolute 'us' timeout into
115 relative 'ms', use code like the following:
</para>
117 <programlisting>uint64_t t;
119 sd_journal_get_timeout(m,
&t);
120 if (t == (uint64_t) -
1)
125 clock_gettime(CLOCK_MONOTONIC,
&ts);
126 n = (uint64_t) ts.tv_sec *
1000000 + ts.tv_nsec /
1000;
127 msec = t
> n ? (int) ((t - n +
999) /
1000) :
0;
130 <para>The code above does not do any error checking for brevity's
131 sake. The calculated
<varname>msec
</varname> integer can be passed
132 directly as
<function>poll()
</function>'s timeout
135 <para>After each
<function>poll()
</function> wake-up
136 <function>sd_journal_process()
</function> needs to be called to
137 process events. This call will also indicate what kind of change
138 has been detected (see below; note that spurious wake-ups are
141 <para>A synchronous alternative for using
142 <function>sd_journal_get_fd()
</function>,
143 <function>sd_journal_get_events()
</function>,
144 <function>sd_journal_get_timeout()
</function> and
145 <function>sd_journal_process()
</function> is
146 <function>sd_journal_wait()
</function>. It will synchronously wait
147 until the journal gets changed. The maximum time this call sleeps
148 may be controlled with the
<parameter>timeout_usec
</parameter>
149 parameter. Pass
<constant>(uint64_t) -
1</constant> to wait
150 indefinitely. Internally this call simply combines
151 <function>sd_journal_get_fd()
</function>,
152 <function>sd_journal_get_events()
</function>,
153 <function>sd_journal_get_timeout()
</function>,
154 <function>poll()
</function> and
155 <function>sd_journal_process()
</function> into one.
</para>
157 <para><function>sd_journal_reliable_fd()
</function> may be used to
158 check whether the wakeup events from the file descriptor returned
159 by
<function>sd_journal_get_fd()
</function> are known to be
160 immediately triggered. On certain file systems where file change
161 events from the OS are not available (such as NFS) changes need to
162 be polled for repeatedly, and hence are detected only with a
163 certain latency. This call will return a positive value if the
164 journal changes are detected immediately and zero when they need
165 to be polled for and hence might be noticed only with a certain
166 latency. Note that there is usually no need to invoke this function
167 directly as
<function>sd_journal_get_timeout()
</function> on these
168 file systems will ask for timeouts explicitly anyway.
</para>
172 <title>Return Value
</title>
174 <para><function>sd_journal_get_fd()
</function> returns a valid
175 file descriptor on success or a negative errno-style error
178 <para><function>sd_journal_get_events()
</function> returns a
179 combination of
<constant>POLLIN
</constant>,
180 <constant>POLLOUT
</constant> and suchlike on success or a negative
181 errno-style error code.
</para>
183 <para><function>sd_journal_reliable_fd()
</function> returns a
184 positive integer if the file descriptor returned by
185 <function>sd_journal_get_fd()
</function> will generate wake-ups
186 immediately for all journal changes. Returns
0 if there might be a
187 latency involved.
</para>
189 <para><function>sd_journal_process()
</function> and
<function>sd_journal_wait()
</function> return a negative
190 errno-style error code, or one of
<constant>SD_JOURNAL_NOP
</constant>,
<constant>SD_JOURNAL_APPEND
</constant> or
191 <constant>SD_JOURNAL_INVALIDATE
</constant> on success:
</para>
194 <listitem><para>If
<constant>SD_JOURNAL_NOP
</constant> is returned, the journal did not change since the last
195 invocation.
</para></listitem>
197 <listitem><para>If
<constant>SD_JOURNAL_APPEND
</constant> is returned, new entries have been appended to the end
198 of the journal. In this case it is sufficient to simply continue reading at the previous end location of the
199 journal, to read the newly added entries.
</para></listitem>
201 <listitem><para>If
<constant>SD_JOURNAL_INVALIDATE
</constant>, journal files were added to or removed from the
202 set of journal files watched (e.g. due to rotation or vacuuming), and thus entries might have appeared or
203 disappeared at arbitrary places in the log stream, possibly before or after the previous end of the log
204 stream. If
<constant>SD_JOURNAL_INVALIDATE
</constant> is returned, live-view UIs that want to reflect on screen
205 the precise state of the log data on disk should probably refresh their entire display (relative to the cursor of
206 the log entry on the top of the screen). Programs only interested in a strictly sequential stream of log data may
207 treat
<constant>SD_JOURNAL_INVALIDATE
</constant> the same way as
<constant>SD_JOURNAL_APPEND
</constant>, thus
208 ignoring any changes to the log view earlier than the old end of the log stream.
</para></listitem>
213 <title>Signal safety
</title>
215 <para>In general,
<function>sd_journal_get_fd()
</function>,
<function>sd_journal_get_events()
</function>, and
216 <function>sd_journal_get_timeout()
</function> are
<emphasis>not
</emphasis> "async signal safe" in the meaning of
218 project='man-pages'
><refentrytitle>signal-safety
</refentrytitle><manvolnum>7</manvolnum></citerefentry>.
219 Nevertheless, only the first call to any of those three functions performs unsafe operations, so subsequent calls
220 <emphasis>are
</emphasis> safe.
</para>
222 <para><function>sd_journal_process()
</function> and
<function>sd_journal_wait()
</function> are not
223 safe.
<function>sd_journal_reliable_fd()
</function> is safe.
</para>
229 <para>The
<function>sd_journal_get_fd()
</function>,
230 <function>sd_journal_get_events()
</function>,
231 <function>sd_journal_reliable_fd()
</function>,
232 <function>sd_journal_process()
</function> and
233 <function>sd_journal_wait()
</function> interfaces are available as
234 a shared library, which can be compiled and linked to with the
235 <constant>libsystemd
</constant> <citerefentry project='die-net'
><refentrytitle>pkg-config
</refentrytitle><manvolnum>1</manvolnum></citerefentry>
240 <title>Examples
</title>
242 <para>Iterating through the journal, in a live view tracking all
245 <programlisting><xi:include href=
"journal-iterate-wait.c" parse=
"text" /></programlisting>
247 <para>Waiting with
<function>poll()
</function> (this
248 example lacks all error checking for the sake of
251 <programlisting><xi:include href=
"journal-iterate-poll.c" parse=
"text" /></programlisting>
255 <title>See Also
</title>
258 <citerefentry><refentrytitle>systemd
</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
259 <citerefentry><refentrytitle>sd-journal
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
260 <citerefentry><refentrytitle>sd_journal_open
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
261 <citerefentry><refentrytitle>sd_journal_next
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
262 <citerefentry><refentrytitle>poll
</refentrytitle><manvolnum>2</manvolnum></citerefentry>,
263 <citerefentry><refentrytitle>clock_gettime
</refentrytitle><manvolnum>2</manvolnum></citerefentry>