~ubuntu-branches/ubuntu/trusty/systemd/trusty

<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.77.1"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><a href="index.html">Index </a>·

<a href="systemd.directives.html">Directives </a>·

<a href="../python-systemd/index.html">Python </a>·

<a href="../libudev/index.html">libudev </a>·

<a href="../libudev/index.html">gudev </a><span style="float:right">systemd 202</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

interface</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><div class="funcsynopsis"><pre class="funcsynopsisinfo">#include <systemd/sd-journal.h></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="idp3967776"></a><h2>Description</h2><p><code class="function">sd_journal_get_fd()</code> returns

a file descriptor that may be asynchronously polled in

an external event loop and is signaled as soon as the

journal changes, because new entries or files were

added, rotation took place, or files have been

deleted, and similar. The file descriptor is suitable

for usage in

<a href="poll.html"><span class="citerefentry"><span class="refentrytitle">poll</span>(2)</span></a>. Use

<code class="function">sd_journal_get_events()</code> for an

events mask to watch for. The call takes one argument:

the journal context object. Note that not all file

systems are capable of generating the necessary events

for wakeups from this file descriptor for changes to

be noticed immediately. In particular network files

systems do not generate suitable file change events in

all cases. Cases like this can be detected with

<code class="function">sd_journal_reliable_fd()</code>,

below. <code class="function">sd_journal_get_timeout()</code>

will ensure in these cases that wake-ups happen

frequently enough for changes to be noticed, although

with a certain latency.</p><p><code class="function">sd_journal_get_events()</code>

will return the <code class="function">poll()</code> mask to

wait for. This function will return a combination of

<code class="literal">POLLIN</code> and

<code class="literal">POLLOUT</code> and similar to fill into

the <code class="literal">.events</code> field of

<code class="literal">struct pollfd</code>.</p><p><code class="function">sd_journal_get_timeout()</code>

will return a timeout value for usage in <code class="function">poll()</code>. This returns a value in microseconds since the epoch of CLOCK_MONOTONIC for timing out <code class="function">poll()</code> in <code class="literal">timeout_usec</code>. See

<a href="clock_gettime.html"><span class="citerefentry"><span class="refentrytitle">clock_gettime</span>(2)</span></a>

for details about

<code class="literal">CLOCK_MONOTONIC</code>. If there's no

timeout to wait for this will fill in

<code class="literal">(uint64_t) -1</code> instead. Note that

<code class="function">poll()</code> takes a relative timeout

in milliseconds rather than an absolute timeout in

microseconds. To convert the absolute 'us' timeout into

relative 'ms', use code like the following:</p><pre class="programlisting">uint64_t t;

int msec;

sd_journal_get_timeout(m, &t);

if (t == (uint64_t) -1)

msec = -1;

else {

struct timespec ts;

uint64_t n;

clock_getttime(CLOCK_MONOTONIC, &ts);

n = (uint64_t) ts.tv_sec * 1000000 + ts.tv_nsec / 1000;

msec = t > n ? (int) ((t - n + 999) / 1000) : 0;

}</pre><p>The code above does not do any error checking

for brevity's sake. The calculated <code class="literal">msec</code>

integer can be passed directly as

<code class="function">poll()</code>'s timeout

parameter.</p><p>After each <code class="function">poll()</code> wake-up

<code class="function">sd_journal_process()</code> needs to be

called to process events. This call will also indicate

what kind of change has been detected (see below; note

that spurious wake-ups are possible).</p><p>A synchronous alternative for using

<code class="function">sd_journal_get_fd()</code>,

<code class="function">sd_journal_get_events()</code>,

<code class="function">sd_journal_get_timeout()</code> and

<code class="function">sd_journal_process()</code> is

<code class="function">sd_journal_wait()</code>. It will

synchronously wait until the journal gets changed. The

maximum time this call sleeps may be controlled with

the <em class="parameter"><code>timeout_usec</code></em>

parameter. Pass <code class="literal">(uint64_t) -1</code> to

wait indefinitely. Internally this call simply

combines <code class="function">sd_journal_get_fd()</code>,

<code class="function">sd_journal_get_events()</code>,

<code class="function">sd_journal_get_timeout()</code>,

<code class="function">poll()</code> and

<code class="function">sd_journal_process()</code> into

one.</p><p><code class="function">sd_journal_reliable_fd()</code>

may be used to check whether the wakeup events from

the file descriptor returned by

<code class="function">sd_journal_get_fd()</code> are known to

be immediately triggered. On certain file systems

where file change events from the OS are not available

(such as NFS) changes need to be polled for

repeatedly, and hence are detected only with a certain

latency. This call will return a positive value if the

journal changes are detected immediately and zero when

they need to be polled for and hence might be noticed

only with a certain latency. Note that there's usually

no need to invoke this function directly as

<code class="function">sd_journal_get_timeout()</code> on these

file systems will ask for timeouts explicitly

anyway.</p></div><div class="refsect1"><a name="idp59456"></a><h2>Return Value</h2><p><code class="function">sd_journal_get_fd()</code> returns

a valid file descriptor on success or a negative

errno-style error code.</p><p><code class="function">sd_journal_get_events()</code>

returns a combination of <code class="literal">POLLIN</code>,

<code class="literal">POLLOUT</code> and suchlike on success or

a negative errno-style error code.</p><p><code class="function">sd_journal_reliable_fd()</code>

returns a positive integer if the file descriptor

returned by <code class="function">sd_journal_get_fd()</code>

100

will generate wake-ups immediately for all journal

101

changes. Returns 0 if there might be a latency

102

involved.</p><p><code class="function">sd_journal_process()</code> and

103

<code class="function">sd_journal_wait()</code> return one of

104

<code class="literal">SD_JOURNAL_NOP</code>,

105

<code class="literal">SD_JOURNAL_APPEND</code> or

106

<code class="literal">SD_JOURNAL_INVALIDATE</code> on success or

107

a negative errno-style error code. If

108

<code class="literal">SD_JOURNAL_NOP</code> is returned the

109

journal didn't change since the last invocation. If

110

<code class="literal">SD_JOURNAL_APPEND</code> is returned new

111

entries have been appended to the end of the

112

journal. If <code class="literal">SD_JOURNAL_INVALIDATE</code>

113

journal files were added or removed (possibly due to

114

rotation). In the latter event live-view UIs should

115

probably refresh their entire display while in the

116

case of <code class="literal">SD_JOURNAL_APPEND</code> it is

117

sufficient to simply continue reading at the previous

118

end of the journal.</p></div><div class="refsect1"><a name="idp4749904"></a><h2>Notes</h2><p>The <code class="function">sd_journal_get_fd()</code>,

119

<code class="function">sd_journal_get_events()</code>,

120

<code class="function">sd_journal_reliable_fd()</code>,

121

<code class="function">sd_journal_process()</code> and

122

<code class="function">sd_journal_wait()</code> interfaces are

123

available as shared library, which can be compiled and

124

linked to with the

125

<code class="literal">libsystemd-journal</code>

126

<a href="pkg-config.html"><span class="citerefentry"><span class="refentrytitle">pkg-config</span>(1)</span></a>

127

file.</p></div><div class="refsect1"><a name="idp4755728"></a><h2>Examples</h2><p>Iterating through the journal, in a live view tracking all changes:</p><pre class="programlisting">#include <stdio.h>

128

#include <string.h>

129

#include <systemd/sd-journal.h>

130

131

int main(int argc, char *argv[]) {

132

int r;

133

sd_journal *j;

134

r = sd_journal_open(&j, SD_JOURNAL_LOCAL_ONLY);

135

if (r < 0) {

136

fprintf(stderr, "Failed to open journal: %s\n", strerror(-r));

137

return 1;

138

}

139

for (;;) {

140

const void *d;

141

size_t l;

142

r = sd_journal_next(j);

143

if (r < 0) {

144

fprintf(stderr, "Failed to iterate to next entry: %s\n", strerror(-r));

145

break;

146

}

147

if (r == 0) {

148

/* Reached the end, let's wait for changes, and try again */

149

r = sd_journal_wait(j, (uint64_t) -1);

150

if (r < 0) {

151

fprintf(stderr, "Failed to wait for changes: %s\n", strerror(-r));

152

break;

153

}

154

continue;

155

}

156

r = sd_journal_get_data(j, "MESSAGE", &d, &l);

157

if (r < 0) {

158

fprintf(stderr, "Failed to read message field: %s\n", strerror(-r));

159

continue;

160

}

161

printf("%.*s\n", (int) l, (const char*) d);

162

}

163

sd_journal_close(j);

164

return 0;

165

}</pre><p>Waiting with <code class="function">poll()</code> (this

166

example lacks all error checking for the sake of

167

simplicity):</p><pre class="programlisting">#include <sys/poll.h>

168

#include <systemd/sd-journal.h>

169

170

int wait_for_changes(sd_journal *j) {

171

struct pollfd pollfd;

172

int msec;

173

174

sd_journal_get_timeout(m, &t);

175

if (t == (uint64_t) -1)

176

msec = -1;

177

else {

178

struct timespec ts;

179

uint64_t n;

180

clock_getttime(CLOCK_MONOTONIC, &ts);

181

n = (uint64_t) ts.tv_sec * 1000000 + ts.tv_nsec / 1000;

182

msec = t > n ? (int) ((t - n + 999) / 1000) : 0;

183

}

184

185

pollfd.fd = sd_journal_get_fd(j);

186

pollfd.events = sd_journal_get_events(j);

187

poll(&pollfd, 1, msec);

188

return sd_journal_process(j);

189

}

190

</pre></div><div class="refsect1"><a name="idp4762352"></a><h2>See Also</h2><p>

191

<a href="systemd.html"><span class="citerefentry"><span class="refentrytitle">systemd</span>(1)</span></a>,

192

<a href="sd-journal.html"><span class="citerefentry"><span class="refentrytitle">sd-journal</span>(3)</span></a>,

193

<a href="sd_journal_open.html"><span class="citerefentry"><span class="refentrytitle">sd_journal_open</span>(3)</span></a>,

194

<a href="sd_journal_next.html"><span class="citerefentry"><span class="refentrytitle">sd_journal_next</span>(3)</span></a>,

195

<a href="poll.html"><span class="citerefentry"><span class="refentrytitle">poll</span>(2)</span></a>,

196

<a href="clock_gettime.html"><span class="citerefentry"><span class="refentrytitle">clock_gettime</span>(2)</span></a>

197

</p></div></div></body></html>

Older »