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 This file is part of systemd.
8 Copyright 2012 Lennart Poettering
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.
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.
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/>.
24 <refentry id="sd_journal_get_fd">
27 <title>sd_journal_get_fd</title>
28 <productname>systemd</productname>
32 <contrib>Developer</contrib>
33 <firstname>Lennart</firstname>
34 <surname>Poettering</surname>
35 <email>lennart@poettering.net</email>
41 <refentrytitle>sd_journal_get_fd</refentrytitle>
42 <manvolnum>3</manvolnum>
46 <refname>sd_journal_get_fd</refname>
47 <refname>sd_journal_get_events</refname>
48 <refname>sd_journal_get_timeout</refname>
49 <refname>sd_journal_process</refname>
50 <refname>sd_journal_wait</refname>
51 <refname>sd_journal_reliable_fd</refname>
52 <refname>SD_JOURNAL_NOP</refname>
53 <refname>SD_JOURNAL_APPEND</refname>
54 <refname>SD_JOURNAL_INVALIDATE</refname>
55 <refpurpose>Journal change notification
56 interface</refpurpose>
61 <funcsynopsisinfo>#include <systemd/sd-journal.h></funcsynopsisinfo>
64 <funcdef>int <function>sd_journal_get_fd</function></funcdef>
65 <paramdef>sd_journal *<parameter>j</parameter></paramdef>
69 <funcdef>int <function>sd_journal_get_events</function></funcdef>
70 <paramdef>sd_journal *<parameter>j</parameter></paramdef>
74 <funcdef>int <function>sd_journal_get_timeout</function></funcdef>
75 <paramdef>sd_journal *<parameter>j</parameter></paramdef>
76 <paramdef>uint64_t *<parameter>timeout_usec</parameter></paramdef>
80 <funcdef>int <function>sd_journal_process</function></funcdef>
81 <paramdef>sd_journal *<parameter>j</parameter></paramdef>
85 <funcdef>int <function>sd_journal_wait</function></funcdef>
86 <paramdef>sd_journal *<parameter>j</parameter></paramdef>
87 <paramdef>uint64_t <parameter>timeout_usec</parameter></paramdef>
91 <funcdef>int <function>sd_journal_reliable_fd</function></funcdef>
92 <paramdef>sd_journal *<parameter>j</parameter></paramdef>
99 <title>Description</title>
101 <para><function>sd_journal_get_fd()</function> returns a file
102 descriptor that may be asynchronously polled in an external event
103 loop and is signaled as soon as the journal changes, because new
104 entries or files were added, rotation took place, or files have
105 been deleted, and similar. The file descriptor is suitable for
107 <citerefentry><refentrytitle>poll</refentrytitle><manvolnum>2</manvolnum></citerefentry>.
108 Use <function>sd_journal_get_events()</function> for an events
109 mask to watch for. The call takes one argument: the journal
110 context object. Note that not all file systems are capable of
111 generating the necessary events for wakeups from this file
112 descriptor for changes to be noticed immediately. In particular
113 network files systems do not generate suitable file change events
114 in all cases. Cases like this can be detected with
115 <function>sd_journal_reliable_fd()</function>, below.
116 <function>sd_journal_get_timeout()</function> will ensure in these
117 cases that wake-ups happen frequently enough for changes to be
118 noticed, although with a certain latency.</para>
120 <para><function>sd_journal_get_events()</function> will return the
121 <function>poll()</function> mask to wait for. This function will
122 return a combination of <constant>POLLIN</constant> and
123 <constant>POLLOUT</constant> and similar to fill into the
124 <literal>.events</literal> field of <varname>struct
125 pollfd</varname>.</para>
127 <para><function>sd_journal_get_timeout()</function> will return a
128 timeout value for usage in <function>poll()</function>. This
129 returns a value in microseconds since the epoch of
130 <constant>CLOCK_MONOTONIC</constant> for timing out
131 <function>poll()</function> in <varname>timeout_usec</varname>.
133 <citerefentry><refentrytitle>clock_gettime</refentrytitle><manvolnum>2</manvolnum></citerefentry>
134 for details about <constant>CLOCK_MONOTONIC</constant>. If there
135 is no timeout to wait for, this will fill in <constant>(uint64_t)
136 -1</constant> instead. Note that <function>poll()</function> takes
137 a relative timeout in milliseconds rather than an absolute timeout
138 in microseconds. To convert the absolute 'us' timeout into
139 relative 'ms', use code like the following:</para>
141 <programlisting>uint64_t t;
143 sd_journal_get_timeout(m, &t);
144 if (t == (uint64_t) -1)
149 clock_getttime(CLOCK_MONOTONIC, &ts);
150 n = (uint64_t) ts.tv_sec * 1000000 + ts.tv_nsec / 1000;
151 msec = t > n ? (int) ((t - n + 999) / 1000) : 0;
154 <para>The code above does not do any error checking for brevity's
155 sake. The calculated <varname>msec</varname> integer can be passed
156 directly as <function>poll()</function>'s timeout
159 <para>After each <function>poll()</function> wake-up
160 <function>sd_journal_process()</function> needs to be called to
161 process events. This call will also indicate what kind of change
162 has been detected (see below; note that spurious wake-ups are
165 <para>A synchronous alternative for using
166 <function>sd_journal_get_fd()</function>,
167 <function>sd_journal_get_events()</function>,
168 <function>sd_journal_get_timeout()</function> and
169 <function>sd_journal_process()</function> is
170 <function>sd_journal_wait()</function>. It will synchronously wait
171 until the journal gets changed. The maximum time this call sleeps
172 may be controlled with the <parameter>timeout_usec</parameter>
173 parameter. Pass <constant>(uint64_t) -1</constant> to wait
174 indefinitely. Internally this call simply combines
175 <function>sd_journal_get_fd()</function>,
176 <function>sd_journal_get_events()</function>,
177 <function>sd_journal_get_timeout()</function>,
178 <function>poll()</function> and
179 <function>sd_journal_process()</function> into one.</para>
181 <para><function>sd_journal_reliable_fd()</function> may be used to
182 check whether the wakeup events from the file descriptor returned
183 by <function>sd_journal_get_fd()</function> are known to be
184 immediately triggered. On certain file systems where file change
185 events from the OS are not available (such as NFS) changes need to
186 be polled for repeatedly, and hence are detected only with a
187 certain latency. This call will return a positive value if the
188 journal changes are detected immediately and zero when they need
189 to be polled for and hence might be noticed only with a certain
190 latency. Note that there's usually no need to invoke this function
191 directly as <function>sd_journal_get_timeout()</function> on these
192 file systems will ask for timeouts explicitly anyway.</para>
196 <title>Return Value</title>
198 <para><function>sd_journal_get_fd()</function> returns a valid
199 file descriptor on success or a negative errno-style error
202 <para><function>sd_journal_get_events()</function> returns a
203 combination of <constant>POLLIN</constant>,
204 <constant>POLLOUT</constant> and suchlike on success or a negative
205 errno-style error code.</para>
207 <para><function>sd_journal_reliable_fd()</function> returns a
208 positive integer if the file descriptor returned by
209 <function>sd_journal_get_fd()</function> will generate wake-ups
210 immediately for all journal changes. Returns 0 if there might be a
211 latency involved.</para>
213 <para><function>sd_journal_process()</function> and
214 <function>sd_journal_wait()</function> return one of
215 <constant>SD_JOURNAL_NOP</constant>,
216 <constant>SD_JOURNAL_APPEND</constant> or
217 <constant>SD_JOURNAL_INVALIDATE</constant> on success or a
218 negative errno-style error code. If
219 <constant>SD_JOURNAL_NOP</constant> is returned, the journal did
220 not change since the last invocation. If
221 <constant>SD_JOURNAL_APPEND</constant> is returned, new entries
222 have been appended to the end of the journal. If
223 <constant>SD_JOURNAL_INVALIDATE</constant>, journal files were
224 added or removed (possibly due to rotation). In the latter event,
225 live-view UIs should probably refresh their entire display, while
226 in the case of <constant>SD_JOURNAL_APPEND</constant>, it is
227 sufficient to simply continue reading at the previous end of the
234 <para>The <function>sd_journal_get_fd()</function>,
235 <function>sd_journal_get_events()</function>,
236 <function>sd_journal_reliable_fd()</function>,
237 <function>sd_journal_process()</function> and
238 <function>sd_journal_wait()</function> interfaces are available as
239 a shared library, which can be compiled and linked to with the
240 <constant>libsystemd</constant> <citerefentry project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry>
245 <title>Examples</title>
247 <para>Iterating through the journal, in a live view tracking all
250 <programlisting>#include <stdio.h>
251 #include <string.h>
252 #include <systemd/sd-journal.h>
254 int main(int argc, char *argv[]) {
257 r = sd_journal_open(&j, SD_JOURNAL_LOCAL_ONLY);
259 fprintf(stderr, "Failed to open journal: %s\n", strerror(-r));
265 r = sd_journal_next(j);
267 fprintf(stderr, "Failed to iterate to next entry: %s\n", strerror(-r));
271 /* Reached the end, let's wait for changes, and try again */
272 r = sd_journal_wait(j, (uint64_t) -1);
274 fprintf(stderr, "Failed to wait for changes: %s\n", strerror(-r));
279 r = sd_journal_get_data(j, "MESSAGE", &d, &l);
281 fprintf(stderr, "Failed to read message field: %s\n", strerror(-r));
284 printf("%.*s\n", (int) l, (const char*) d);
290 <para>Waiting with <function>poll()</function> (this
291 example lacks all error checking for the sake of
294 <programlisting>#include <poll.h>
295 #include <systemd/sd-journal.h>
297 int wait_for_changes(sd_journal *j) {
298 struct pollfd pollfd;
301 sd_journal_get_timeout(m, &t);
302 if (t == (uint64_t) -1)
307 clock_getttime(CLOCK_MONOTONIC, &ts);
308 n = (uint64_t) ts.tv_sec * 1000000 + ts.tv_nsec / 1000;
309 msec = t > n ? (int) ((t - n + 999) / 1000) : 0;
312 pollfd.fd = sd_journal_get_fd(j);
313 pollfd.events = sd_journal_get_events(j);
314 poll(&pollfd, 1, msec);
315 return sd_journal_process(j);
320 <title>See Also</title>
323 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
324 <citerefentry><refentrytitle>sd-journal</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
325 <citerefentry><refentrytitle>sd_journal_open</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
326 <citerefentry><refentrytitle>sd_journal_next</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
327 <citerefentry><refentrytitle>poll</refentrytitle><manvolnum>2</manvolnum></citerefentry>,
328 <citerefentry><refentrytitle>clock_gettime</refentrytitle><manvolnum>2</manvolnum></citerefentry>