]> git.proxmox.com Git - systemd.git/blob - man/sd_journal_process.html
deb02e768c2f9f916e556152f5f09eb3735aef55
[systemd.git] / man / sd_journal_process.html
1 <html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>sd_journal_get_fd</title><meta name="generator" content="DocBook XSL Stylesheets V1.78.1"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><style>
2 a.headerlink {
3 color: #c60f0f;
4 font-size: 0.8em;
5 padding: 0 4px 0 4px;
6 text-decoration: none;
7 visibility: hidden;
8 }
9
10 a.headerlink:hover {
11 background-color: #c60f0f;
12 color: white;
13 }
14
15 h1:hover > a.headerlink, h2:hover > a.headerlink, h3:hover > a.headerlink, dt:hover > a.headerlink {
16 visibility: visible;
17 }
18 </style><a href="index.html">Index </a>·
19 <a href="systemd.directives.html">Directives </a>·
20 <a href="../python-systemd/index.html">Python </a>·
21 <a href="../libudev/index.html">libudev </a>·
22 <a href="../libudev/index.html">gudev </a><span style="float:right">systemd 208</span><hr><div class="refentry"><a name="sd_journal_get_fd"></a><div class="titlepage"></div><div class="refnamediv"><h2>Name</h2><p>sd_journal_get_fd, sd_journal_get_events, sd_journal_get_timeout, sd_journal_process, sd_journal_wait, sd_journal_reliable_fd, SD_JOURNAL_NOP, SD_JOURNAL_APPEND, SD_JOURNAL_INVALIDATE — Journal change notification
23 interface</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><div class="funcsynopsis"><pre class="funcsynopsisinfo">#include &lt;systemd/sd-journal.h&gt;</pre><table border="0" class="funcprototype-table" summary="Function synopsis" style="cellspacing: 0; cellpadding: 0;"><tr><td><code class="funcdef">int <b class="fsfunc">sd_journal_get_fd</b>(</code></td><td>sd_journal* <var class="pdparam">j</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer"> </div><table border="0" class="funcprototype-table" summary="Function synopsis" style="cellspacing: 0; cellpadding: 0;"><tr><td><code class="funcdef">int <b class="fsfunc">sd_journal_get_events</b>(</code></td><td>sd_journal* <var class="pdparam">j</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer"> </div><table border="0" class="funcprototype-table" summary="Function synopsis" style="cellspacing: 0; cellpadding: 0;"><tr><td><code class="funcdef">int <b class="fsfunc">sd_journal_get_timeout</b>(</code></td><td>sd_journal* <var class="pdparam">j</var>, </td></tr><tr><td> </td><td>uint64_t* <var class="pdparam">timeout_usec</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer"> </div><table border="0" class="funcprototype-table" summary="Function synopsis" style="cellspacing: 0; cellpadding: 0;"><tr><td><code class="funcdef">int <b class="fsfunc">sd_journal_process</b>(</code></td><td>sd_journal* <var class="pdparam">j</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer"> </div><table border="0" class="funcprototype-table" summary="Function synopsis" style="cellspacing: 0; cellpadding: 0;"><tr><td><code class="funcdef">int <b class="fsfunc">sd_journal_wait</b>(</code></td><td>sd_journal* <var class="pdparam">j</var>, </td></tr><tr><td> </td><td>uint64_t <var class="pdparam">timeout_usec</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer"> </div><table border="0" class="funcprototype-table" summary="Function synopsis" style="cellspacing: 0; cellpadding: 0;"><tr><td><code class="funcdef">int <b class="fsfunc">sd_journal_reliable_fd</b>(</code></td><td>sd_journal* <var class="pdparam">j</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer"> </div></div></div><div class="refsect1"><a name="idm274704023696"></a><h2 id="Description">Description<a class="headerlink" title="Permalink to this headline" href="#Description"></a></h2><p><code class="function">sd_journal_get_fd()</code> returns
24 a file descriptor that may be asynchronously polled in
25 an external event loop and is signaled as soon as the
26 journal changes, because new entries or files were
27 added, rotation took place, or files have been
28 deleted, and similar. The file descriptor is suitable
29 for usage in
30 <a href="poll.html"><span class="citerefentry"><span class="refentrytitle">poll</span>(2)</span></a>. Use
31 <code class="function">sd_journal_get_events()</code> for an
32 events mask to watch for. The call takes one argument:
33 the journal context object. Note that not all file
34 systems are capable of generating the necessary events
35 for wakeups from this file descriptor for changes to
36 be noticed immediately. In particular network files
37 systems do not generate suitable file change events in
38 all cases. Cases like this can be detected with
39 <code class="function">sd_journal_reliable_fd()</code>,
40 below. <code class="function">sd_journal_get_timeout()</code>
41 will ensure in these cases that wake-ups happen
42 frequently enough for changes to be noticed, although
43 with a certain latency.</p><p><code class="function">sd_journal_get_events()</code>
44 will return the <code class="function">poll()</code> mask to
45 wait for. This function will return a combination of
46 <code class="constant">POLLIN</code> and
47 <code class="constant">POLLOUT</code> and similar to fill into
48 the "<code class="literal">.events</code>" field of
49 <code class="varname">struct pollfd</code>.</p><p><code class="function">sd_journal_get_timeout()</code>
50 will return a timeout value for usage in
51 <code class="function">poll()</code>. This returns a value in
52 microseconds since the epoch of
53 <code class="constant">CLOCK_MONOTONIC</code> for timing out
54 <code class="function">poll()</code> in
55 <code class="varname">timeout_usec</code>. See
56 <a href="clock_gettime.html"><span class="citerefentry"><span class="refentrytitle">clock_gettime</span>(2)</span></a>
57 for details about
58 <code class="constant">CLOCK_MONOTONIC</code>. If there is no
59 timeout to wait for, this will fill in
60 <code class="constant">(uint64_t) -1</code> instead. Note that
61 <code class="function">poll()</code> takes a relative timeout
62 in milliseconds rather than an absolute timeout in
63 microseconds. To convert the absolute 'us' timeout
64 into relative 'ms', use code like the
65 following:</p><pre class="programlisting">uint64_t t;
66 int msec;
67 sd_journal_get_timeout(m, &amp;t);
68 if (t == (uint64_t) -1)
69 msec = -1;
70 else {
71 struct timespec ts;
72 uint64_t n;
73 clock_getttime(CLOCK_MONOTONIC, &amp;ts);
74 n = (uint64_t) ts.tv_sec * 1000000 + ts.tv_nsec / 1000;
75 msec = t &gt; n ? (int) ((t - n + 999) / 1000) : 0;
76 }</pre><p>The code above does not do any error checking
77 for brevity's sake. The calculated <code class="varname">msec</code>
78 integer can be passed directly as
79 <code class="function">poll()</code>'s timeout
80 parameter.</p><p>After each <code class="function">poll()</code> wake-up
81 <code class="function">sd_journal_process()</code> needs to be
82 called to process events. This call will also indicate
83 what kind of change has been detected (see below; note
84 that spurious wake-ups are possible).</p><p>A synchronous alternative for using
85 <code class="function">sd_journal_get_fd()</code>,
86 <code class="function">sd_journal_get_events()</code>,
87 <code class="function">sd_journal_get_timeout()</code> and
88 <code class="function">sd_journal_process()</code> is
89 <code class="function">sd_journal_wait()</code>. It will
90 synchronously wait until the journal gets changed. The
91 maximum time this call sleeps may be controlled with
92 the <em class="parameter"><code>timeout_usec</code></em>
93 parameter. Pass <code class="constant">(uint64_t) -1</code> to
94 wait indefinitely. Internally this call simply
95 combines <code class="function">sd_journal_get_fd()</code>,
96 <code class="function">sd_journal_get_events()</code>,
97 <code class="function">sd_journal_get_timeout()</code>,
98 <code class="function">poll()</code> and
99 <code class="function">sd_journal_process()</code> into
100 one.</p><p><code class="function">sd_journal_reliable_fd()</code>
101 may be used to check whether the wakeup events from
102 the file descriptor returned by
103 <code class="function">sd_journal_get_fd()</code> are known to
104 be immediately triggered. On certain file systems
105 where file change events from the OS are not available
106 (such as NFS) changes need to be polled for
107 repeatedly, and hence are detected only with a certain
108 latency. This call will return a positive value if the
109 journal changes are detected immediately and zero when
110 they need to be polled for and hence might be noticed
111 only with a certain latency. Note that there's usually
112 no need to invoke this function directly as
113 <code class="function">sd_journal_get_timeout()</code> on these
114 file systems will ask for timeouts explicitly
115 anyway.</p></div><div class="refsect1"><a name="idm274703983584"></a><h2 id="Return Value">Return Value<a class="headerlink" title="Permalink to this headline" href="#Return%20Value"></a></h2><p><code class="function">sd_journal_get_fd()</code> returns
116 a valid file descriptor on success or a negative
117 errno-style error code.</p><p><code class="function">sd_journal_get_events()</code>
118 returns a combination of <code class="constant">POLLIN</code>,
119 <code class="constant">POLLOUT</code> and suchlike on success or
120 a negative errno-style error code.</p><p><code class="function">sd_journal_reliable_fd()</code>
121 returns a positive integer if the file descriptor
122 returned by <code class="function">sd_journal_get_fd()</code>
123 will generate wake-ups immediately for all journal
124 changes. Returns 0 if there might be a latency
125 involved.</p><p><code class="function">sd_journal_process()</code> and
126 <code class="function">sd_journal_wait()</code> return one of
127 <code class="constant">SD_JOURNAL_NOP</code>,
128 <code class="constant">SD_JOURNAL_APPEND</code> or
129 <code class="constant">SD_JOURNAL_INVALIDATE</code> on success or
130 a negative errno-style error code. If
131 <code class="constant">SD_JOURNAL_NOP</code> is returned, the
132 journal did not change since the last invocation. If
133 <code class="constant">SD_JOURNAL_APPEND</code> is returned, new
134 entries have been appended to the end of the
135 journal. If <code class="constant">SD_JOURNAL_INVALIDATE</code>,
136 journal files were added or removed (possibly due to
137 rotation). In the latter event, live-view UIs should
138 probably refresh their entire display, while in the
139 case of <code class="constant">SD_JOURNAL_APPEND</code>, it is
140 sufficient to simply continue reading at the previous
141 end of the journal.</p></div><div class="refsect1"><a name="idm274699013792"></a><h2 id="Notes">Notes<a class="headerlink" title="Permalink to this headline" href="#Notes"></a></h2><p>The <code class="function">sd_journal_get_fd()</code>,
142 <code class="function">sd_journal_get_events()</code>,
143 <code class="function">sd_journal_reliable_fd()</code>,
144 <code class="function">sd_journal_process()</code> and
145 <code class="function">sd_journal_wait()</code> interfaces are
146 available as shared library, which can be compiled and
147 linked to with the
148 <code class="constant">libsystemd-journal</code> <a href="pkg-config.html"><span class="citerefentry"><span class="refentrytitle">pkg-config</span>(1)</span></a>
149 file.</p></div><div class="refsect1"><a name="idm274699008208"></a><h2 id="Examples">Examples<a class="headerlink" title="Permalink to this headline" href="#Examples"></a></h2><p>Iterating through the journal, in a live view tracking all changes:</p><pre class="programlisting">#include &lt;stdio.h&gt;
150 #include &lt;string.h&gt;
151 #include &lt;systemd/sd-journal.h&gt;
152
153 int main(int argc, char *argv[]) {
154 int r;
155 sd_journal *j;
156 r = sd_journal_open(&amp;j, SD_JOURNAL_LOCAL_ONLY);
157 if (r &lt; 0) {
158 fprintf(stderr, "Failed to open journal: %s\n", strerror(-r));
159 return 1;
160 }
161 for (;;) {
162 const void *d;
163 size_t l;
164 r = sd_journal_next(j);
165 if (r &lt; 0) {
166 fprintf(stderr, "Failed to iterate to next entry: %s\n", strerror(-r));
167 break;
168 }
169 if (r == 0) {
170 /* Reached the end, let's wait for changes, and try again */
171 r = sd_journal_wait(j, (uint64_t) -1);
172 if (r &lt; 0) {
173 fprintf(stderr, "Failed to wait for changes: %s\n", strerror(-r));
174 break;
175 }
176 continue;
177 }
178 r = sd_journal_get_data(j, "MESSAGE", &amp;d, &amp;l);
179 if (r &lt; 0) {
180 fprintf(stderr, "Failed to read message field: %s\n", strerror(-r));
181 continue;
182 }
183 printf("%.*s\n", (int) l, (const char*) d);
184 }
185 sd_journal_close(j);
186 return 0;
187 }</pre><p>Waiting with <code class="function">poll()</code> (this
188 example lacks all error checking for the sake of
189 simplicity):</p><pre class="programlisting">#include &lt;sys/poll.h&gt;
190 #include &lt;systemd/sd-journal.h&gt;
191
192 int wait_for_changes(sd_journal *j) {
193 struct pollfd pollfd;
194 int msec;
195
196 sd_journal_get_timeout(m, &amp;t);
197 if (t == (uint64_t) -1)
198 msec = -1;
199 else {
200 struct timespec ts;
201 uint64_t n;
202 clock_getttime(CLOCK_MONOTONIC, &amp;ts);
203 n = (uint64_t) ts.tv_sec * 1000000 + ts.tv_nsec / 1000;
204 msec = t &gt; n ? (int) ((t - n + 999) / 1000) : 0;
205 }
206
207 pollfd.fd = sd_journal_get_fd(j);
208 pollfd.events = sd_journal_get_events(j);
209 poll(&amp;pollfd, 1, msec);
210 return sd_journal_process(j);
211 }
212 </pre></div><div class="refsect1"><a name="idm274699001584"></a><h2 id="See Also">See Also<a class="headerlink" title="Permalink to this headline" href="#See%20Also"></a></h2><p>
213 <a href="systemd.html"><span class="citerefentry"><span class="refentrytitle">systemd</span>(1)</span></a>,
214 <a href="sd-journal.html"><span class="citerefentry"><span class="refentrytitle">sd-journal</span>(3)</span></a>,
215 <a href="sd_journal_open.html"><span class="citerefentry"><span class="refentrytitle">sd_journal_open</span>(3)</span></a>,
216 <a href="sd_journal_next.html"><span class="citerefentry"><span class="refentrytitle">sd_journal_next</span>(3)</span></a>,
217 <a href="poll.html"><span class="citerefentry"><span class="refentrytitle">poll</span>(2)</span></a>,
218 <a href="clock_gettime.html"><span class="citerefentry"><span class="refentrytitle">clock_gettime</span>(2)</span></a>
219 </p></div></div></body></html>