chiark / gitweb /
service: add FailureAction= option
[elogind.git] / 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_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>
57         </refnamediv>
58
59         <refsynopsisdiv>
60                 <funcsynopsis>
61                         <funcsynopsisinfo>#include &lt;systemd/sd-journal.h&gt;</funcsynopsisinfo>
62
63                         <funcprototype>
64                                 <funcdef>int <function>sd_journal_get_fd</function></funcdef>
65                                 <paramdef>sd_journal* <parameter>j</parameter></paramdef>
66                         </funcprototype>
67
68                         <funcprototype>
69                                 <funcdef>int <function>sd_journal_get_events</function></funcdef>
70                                 <paramdef>sd_journal* <parameter>j</parameter></paramdef>
71                         </funcprototype>
72
73                         <funcprototype>
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>
77                         </funcprototype>
78
79                         <funcprototype>
80                                 <funcdef>int <function>sd_journal_process</function></funcdef>
81                                 <paramdef>sd_journal* <parameter>j</parameter></paramdef>
82                         </funcprototype>
83
84                         <funcprototype>
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>
88                         </funcprototype>
89
90                         <funcprototype>
91                                 <funcdef>int <function>sd_journal_reliable_fd</function></funcdef>
92                                 <paramdef>sd_journal* <parameter>j</parameter></paramdef>
93                         </funcprototype>
94
95                 </funcsynopsis>
96         </refsynopsisdiv>
97
98         <refsect1>
99                 <title>Description</title>
100
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
107                 for usage in
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>
122
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>
130
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>
139                 for details about
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
147                 following:</para>
148
149                 <programlisting>uint64_t t;
150 int msec;
151 sd_journal_get_timeout(m, &amp;t);
152 if (t == (uint64_t) -1)
153         msec = -1;
154 else {
155         struct timespec ts;
156         uint64_t n;
157         clock_getttime(CLOCK_MONOTONIC, &amp;ts);
158         n = (uint64_t) ts.tv_sec * 1000000 + ts.tv_nsec / 1000;
159         msec = t > n ? (int) ((t - n + 999) / 1000) : 0;
160 }</programlisting>
161
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
166                 parameter.</para>
167
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>
173
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
190                 one.</para>
191
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
207                 anyway.</para>
208         </refsect1>
209
210         <refsect1>
211                 <title>Return Value</title>
212
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>
216
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>
221
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
227                 involved.</para>
228
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>
246         </refsect1>
247
248         <refsect1>
249                 <title>Notes</title>
250
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 a shared library, which can be compiled and
257                 linked to with the
258                 <constant>libsystemd</constant> <citerefentry><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry>
259                 file.</para>
260         </refsect1>
261
262         <refsect1>
263                 <title>Examples</title>
264
265                 <para>Iterating through the journal, in a live view tracking all changes:</para>
266
267                 <programlisting>#include &lt;stdio.h&gt;
268 #include &lt;string.h&gt;
269 #include &lt;systemd/sd-journal.h&gt;
270
271 int main(int argc, char *argv[]) {
272         int r;
273         sd_journal *j;
274         r = sd_journal_open(&amp;j, SD_JOURNAL_LOCAL_ONLY);
275         if (r &lt; 0) {
276                 fprintf(stderr, "Failed to open journal: %s\n", strerror(-r));
277                 return 1;
278         }
279         for (;;)  {
280                 const void *d;
281                 size_t l;
282                 r = sd_journal_next(j);
283                 if (r &lt; 0) {
284                         fprintf(stderr, "Failed to iterate to next entry: %s\n", strerror(-r));
285                         break;
286                 }
287                 if (r == 0) {
288                         /* Reached the end, let's wait for changes, and try again */
289                         r = sd_journal_wait(j, (uint64_t) -1);
290                         if (r &lt; 0) {
291                                 fprintf(stderr, "Failed to wait for changes: %s\n", strerror(-r));
292                                 break;
293                         }
294                         continue;
295                 }
296                 r = sd_journal_get_data(j, "MESSAGE", &amp;d, &amp;l);
297                 if (r &lt; 0) {
298                         fprintf(stderr, "Failed to read message field: %s\n", strerror(-r));
299                         continue;
300                 }
301                 printf("%.*s\n", (int) l, (const char*) d);
302         }
303         sd_journal_close(j);
304         return 0;
305 }</programlisting>
306
307                 <para>Waiting with <function>poll()</function> (this
308                 example lacks all error checking for the sake of
309                 simplicity):</para>
310
311                 <programlisting>#include &lt;sys/poll.h&gt;
312 #include &lt;systemd/sd-journal.h&gt;
313
314 int wait_for_changes(sd_journal *j) {
315         struct pollfd pollfd;
316         int msec;
317
318         sd_journal_get_timeout(m, &amp;t);
319         if (t == (uint64_t) -1)
320                 msec = -1;
321         else {
322                 struct timespec ts;
323                 uint64_t n;
324                 clock_getttime(CLOCK_MONOTONIC, &amp;ts);
325                 n = (uint64_t) ts.tv_sec * 1000000 + ts.tv_nsec / 1000;
326                 msec = t > n ? (int) ((t - n + 999) / 1000) : 0;
327         }
328
329         pollfd.fd = sd_journal_get_fd(j);
330         pollfd.events = sd_journal_get_events(j);
331         poll(&amp;pollfd, 1, msec);
332         return sd_journal_process(j);
333 }</programlisting>
334         </refsect1>
335
336         <refsect1>
337                 <title>See Also</title>
338
339                 <para>
340                         <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
341                         <citerefentry><refentrytitle>sd-journal</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
342                         <citerefentry><refentrytitle>sd_journal_open</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
343                         <citerefentry><refentrytitle>sd_journal_next</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
344                         <citerefentry><refentrytitle>poll</refentrytitle><manvolnum>2</manvolnum></citerefentry>,
345                         <citerefentry><refentrytitle>clock_gettime</refentrytitle><manvolnum>2</manvolnum></citerefentry>
346                 </para>
347         </refsect1>
348
349 </refentry>