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
102 a file descriptor that may be asynchronously polled in
103 an external event loop and is signaled as soon as the
104 journal changes, because new entries or files were
105 added, rotation took place, or files have been
106 deleted, and similar. The file descriptor is suitable
108 <citerefentry><refentrytitle>poll
</refentrytitle><manvolnum>2</manvolnum></citerefentry>. Use
109 <function>sd_journal_get_events()
</function> for an
110 events mask to watch for. The call takes one argument:
111 the journal context object. Note that not all file
112 systems are capable of generating the necessary events
113 for wakeups from this file descriptor for changes to
114 be noticed immediately. In particular network files
115 systems do not generate suitable file change events in
116 all cases. Cases like this can be detected with
117 <function>sd_journal_reliable_fd()
</function>,
118 below.
<function>sd_journal_get_timeout()
</function>
119 will ensure in these cases that wake-ups happen
120 frequently enough for changes to be noticed, although
121 with a certain latency.
</para>
123 <para><function>sd_journal_get_events()
</function>
124 will return the
<function>poll()
</function> mask to
125 wait for. This function will return a combination of
126 <constant>POLLIN
</constant> and
127 <constant>POLLOUT
</constant> and similar to fill into
128 the
<literal>.events
</literal> field of
129 <varname>struct pollfd
</varname>.
</para>
131 <para><function>sd_journal_get_timeout()
</function>
132 will return a timeout value for usage in
133 <function>poll()
</function>. This returns a value in
134 microseconds since the epoch of
135 <constant>CLOCK_MONOTONIC
</constant> for timing out
136 <function>poll()
</function> in
137 <varname>timeout_usec
</varname>. See
138 <citerefentry><refentrytitle>clock_gettime
</refentrytitle><manvolnum>2</manvolnum></citerefentry>
140 <constant>CLOCK_MONOTONIC
</constant>. If there is no
141 timeout to wait for, this will fill in
142 <constant>(uint64_t) -
1</constant> instead. Note that
143 <function>poll()
</function> takes a relative timeout
144 in milliseconds rather than an absolute timeout in
145 microseconds. To convert the absolute 'us' timeout
146 into relative 'ms', use code like the
149 <programlisting>uint64_t t;
151 sd_journal_get_timeout(m,
&t);
152 if (t == (uint64_t) -
1)
157 clock_getttime(CLOCK_MONOTONIC,
&ts);
158 n = (uint64_t) ts.tv_sec *
1000000 + ts.tv_nsec /
1000;
159 msec = t
> n ? (int) ((t - n +
999) /
1000) :
0;
162 <para>The code above does not do any error checking
163 for brevity's sake. The calculated
<varname>msec
</varname>
164 integer can be passed directly as
165 <function>poll()
</function>'s timeout
168 <para>After each
<function>poll()
</function> wake-up
169 <function>sd_journal_process()
</function> needs to be
170 called to process events. This call will also indicate
171 what kind of change has been detected (see below; note
172 that spurious wake-ups are possible).
</para>
174 <para>A synchronous alternative for using
175 <function>sd_journal_get_fd()
</function>,
176 <function>sd_journal_get_events()
</function>,
177 <function>sd_journal_get_timeout()
</function> and
178 <function>sd_journal_process()
</function> is
179 <function>sd_journal_wait()
</function>. It will
180 synchronously wait until the journal gets changed. The
181 maximum time this call sleeps may be controlled with
182 the
<parameter>timeout_usec
</parameter>
183 parameter. Pass
<constant>(uint64_t) -
1</constant> to
184 wait indefinitely. Internally this call simply
185 combines
<function>sd_journal_get_fd()
</function>,
186 <function>sd_journal_get_events()
</function>,
187 <function>sd_journal_get_timeout()
</function>,
188 <function>poll()
</function> and
189 <function>sd_journal_process()
</function> into
192 <para><function>sd_journal_reliable_fd()
</function>
193 may be used to check whether the wakeup events from
194 the file descriptor returned by
195 <function>sd_journal_get_fd()
</function> are known to
196 be immediately triggered. On certain file systems
197 where file change events from the OS are not available
198 (such as NFS) changes need to be polled for
199 repeatedly, and hence are detected only with a certain
200 latency. This call will return a positive value if the
201 journal changes are detected immediately and zero when
202 they need to be polled for and hence might be noticed
203 only with a certain latency. Note that there's usually
204 no need to invoke this function directly as
205 <function>sd_journal_get_timeout()
</function> on these
206 file systems will ask for timeouts explicitly
211 <title>Return Value
</title>
213 <para><function>sd_journal_get_fd()
</function> returns
214 a valid file descriptor on success or a negative
215 errno-style error code.
</para>
217 <para><function>sd_journal_get_events()
</function>
218 returns a combination of
<constant>POLLIN
</constant>,
219 <constant>POLLOUT
</constant> and suchlike on success or
220 a negative errno-style error code.
</para>
222 <para><function>sd_journal_reliable_fd()
</function>
223 returns a positive integer if the file descriptor
224 returned by
<function>sd_journal_get_fd()
</function>
225 will generate wake-ups immediately for all journal
226 changes. Returns
0 if there might be a latency
229 <para><function>sd_journal_process()
</function> and
230 <function>sd_journal_wait()
</function> return one of
231 <constant>SD_JOURNAL_NOP
</constant>,
232 <constant>SD_JOURNAL_APPEND
</constant> or
233 <constant>SD_JOURNAL_INVALIDATE
</constant> on success or
234 a negative errno-style error code. If
235 <constant>SD_JOURNAL_NOP
</constant> is returned, the
236 journal did not change since the last invocation. If
237 <constant>SD_JOURNAL_APPEND
</constant> is returned, new
238 entries have been appended to the end of the
239 journal. If
<constant>SD_JOURNAL_INVALIDATE
</constant>,
240 journal files were added or removed (possibly due to
241 rotation). In the latter event, live-view UIs should
242 probably refresh their entire display, while in the
243 case of
<constant>SD_JOURNAL_APPEND
</constant>, it is
244 sufficient to simply continue reading at the previous
245 end of the journal.
</para>
251 <para>The
<function>sd_journal_get_fd()
</function>,
252 <function>sd_journal_get_events()
</function>,
253 <function>sd_journal_reliable_fd()
</function>,
254 <function>sd_journal_process()
</function> and
255 <function>sd_journal_wait()
</function> interfaces are
256 available as shared library, which can be compiled and
258 <constant>libsystemd-journal
</constant> <citerefentry><refentrytitle>pkg-config
</refentrytitle><manvolnum>1</manvolnum></citerefentry>
263 <title>Examples
</title>
265 <para>Iterating through the journal, in a live view tracking all changes:
</para>
267 <programlisting>#include
<stdio.h
>
268 #include
<string.h
>
269 #include
<systemd/sd-journal.h
>
271 int main(int argc, char *argv[]) {
274 r = sd_journal_open(
&j, SD_JOURNAL_LOCAL_ONLY);
276 fprintf(stderr,
"Failed to open journal: %s\n", strerror(-r));
282 r = sd_journal_next(j);
284 fprintf(stderr,
"Failed to iterate to next entry: %s\n", strerror(-r));
288 /* Reached the end, let's wait for changes, and try again */
289 r = sd_journal_wait(j, (uint64_t) -
1);
291 fprintf(stderr,
"Failed to wait for changes: %s\n", strerror(-r));
296 r = sd_journal_get_data(j,
"MESSAGE",
&d,
&l);
298 fprintf(stderr,
"Failed to read message field: %s\n", strerror(-r));
301 printf(
"%.*s\n", (int) l, (const char*) d);
307 <para>Waiting with
<function>poll()
</function> (this
308 example lacks all error checking for the sake of
311 <programlisting>#include
<sys/poll.h
>
312 #include
<systemd/sd-journal.h
>
314 int wait_for_changes(sd_journal *j) {
315 struct pollfd pollfd;
318 sd_journal_get_timeout(m,
&t);
319 if (t == (uint64_t) -
1)
324 clock_getttime(CLOCK_MONOTONIC,
&ts);
325 n = (uint64_t) ts.tv_sec *
1000000 + ts.tv_nsec /
1000;
326 msec = t
> n ? (int) ((t - n +
999) /
1000) :
0;
329 pollfd.fd = sd_journal_get_fd(j);
330 pollfd.events = sd_journal_get_events(j);
331 poll(
&pollfd,
1, msec);
332 return sd_journal_process(j);
338 <title>See Also
</title>
341 <citerefentry><refentrytitle>systemd
</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
342 <citerefentry><refentrytitle>sd-journal
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
343 <citerefentry><refentrytitle>sd_journal_open
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
344 <citerefentry><refentrytitle>sd_journal_next
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
345 <citerefentry><refentrytitle>poll
</refentrytitle><manvolnum>2</manvolnum></citerefentry>,
346 <citerefentry><refentrytitle>clock_gettime
</refentrytitle><manvolnum>2</manvolnum></citerefentry>