[systemd.git] / man / sd_journal_reliable_fd.html

<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>
    a.headerlink {
      color: #c60f0f;
      font-size: 0.8em;
      padding: 0 4px 0 4px;
      text-decoration: none;
      visibility: hidden;
    }

    a.headerlink:hover {
      background-color: #c60f0f;
      color: white;
    }

    h1:hover > a.headerlink, h2:hover > a.headerlink, h3:hover > a.headerlink, dt:hover > a.headerlink {
      visibility: visible;
    }
  </style><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 220</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 &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="idm139781237630992"></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 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="http://man7.org/linux/man-pages/man2/poll.2.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="constant">POLLIN</code> and
    <code class="constant">POLLOUT</code> and similar to fill into the
    "<code class="literal">.events</code>" field of <code class="varname">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
    <code class="constant">CLOCK_MONOTONIC</code> for timing out
    <code class="function">poll()</code> in <code class="varname">timeout_usec</code>.
    See
    <a href="http://man7.org/linux/man-pages/man2/clock_gettime.2.html"><span class="citerefentry"><span class="refentrytitle">clock_gettime</span>(2)</span></a>
    for details about <code class="constant">CLOCK_MONOTONIC</code>. If there
    is no timeout to wait for, this will fill in <code class="constant">(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, &amp;t);
if (t == (uint64_t) -1)
  msec = -1;
else {
  struct timespec ts;
  uint64_t n;
  clock_getttime(CLOCK_MONOTONIC, &amp;ts);
  n = (uint64_t) ts.tv_sec * 1000000 + ts.tv_nsec / 1000;
  msec = t &gt; 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="varname">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="constant">(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="idm139781237699632"></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 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="constant">POLLIN</code>,
    <code class="constant">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> will generate wake-ups
    immediately for all journal changes. Returns 0 if there might be a
    latency involved.</p><p><code class="function">sd_journal_process()</code> and
    <code class="function">sd_journal_wait()</code> return one of
    <code class="constant">SD_JOURNAL_NOP</code>,
    <code class="constant">SD_JOURNAL_APPEND</code> or
    <code class="constant">SD_JOURNAL_INVALIDATE</code> on success or a
    negative errno-style error code. If
    <code class="constant">SD_JOURNAL_NOP</code> is returned, the journal did
    not change since the last invocation. If
    <code class="constant">SD_JOURNAL_APPEND</code> is returned, new entries
    have been appended to the end of the journal. If
    <code class="constant">SD_JOURNAL_INVALIDATE</code>, journal files were
    added or removed (possibly due to rotation). In the latter event,
    live-view UIs should probably refresh their entire display, while
    in the case of <code class="constant">SD_JOURNAL_APPEND</code>, it is
    sufficient to simply continue reading at the previous end of the
    journal.</p></div><div class="refsect1"><a name="idm139781232957536"></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>,
    <code class="function">sd_journal_get_events()</code>,
    <code class="function">sd_journal_reliable_fd()</code>,
    <code class="function">sd_journal_process()</code> and
    <code class="function">sd_journal_wait()</code> interfaces are available as
    a shared library, which can be compiled and linked to with the
    <code class="constant">libsystemd</code> <a href="http://linux.die.net/man/1/pkg-config"><span class="citerefentry"><span class="refentrytitle">pkg-config</span>(1)</span></a>
    file.</p></div><div class="refsect1"><a name="idm139781232951760"></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;
#include &lt;string.h&gt;
#include &lt;systemd/sd-journal.h&gt;

int main(int argc, char *argv[]) {
  int r;
  sd_journal *j;
  r = sd_journal_open(&amp;j, SD_JOURNAL_LOCAL_ONLY);
  if (r &lt; 0) {
    fprintf(stderr, "Failed to open journal: %s\n", strerror(-r));
    return 1;
  }
  for (;;)  {
    const void *d;
    size_t l;
    r = sd_journal_next(j);
    if (r &lt; 0) {
      fprintf(stderr, "Failed to iterate to next entry: %s\n", strerror(-r));
      break;
    }
    if (r == 0) {
      /* Reached the end, let's wait for changes, and try again */
      r = sd_journal_wait(j, (uint64_t) -1);
      if (r &lt; 0) {
        fprintf(stderr, "Failed to wait for changes: %s\n", strerror(-r));
        break;
      }
      continue;
    }
    r = sd_journal_get_data(j, "MESSAGE", &amp;d, &amp;l);
    if (r &lt; 0) {
      fprintf(stderr, "Failed to read message field: %s\n", strerror(-r));
      continue;
    }
    printf("%.*s\n", (int) l, (const char*) d);
  }
  sd_journal_close(j);
  return 0;
}</pre><p>Waiting with <code class="function">poll()</code> (this
    example lacks all error checking for the sake of
    simplicity):</p><pre class="programlisting">#include &lt;poll.h&gt;
#include &lt;systemd/sd-journal.h&gt;

int wait_for_changes(sd_journal *j) {
  struct pollfd pollfd;
  int msec;

  sd_journal_get_timeout(m, &amp;t);
  if (t == (uint64_t) -1)
    msec = -1;
  else {
    struct timespec ts;
    uint64_t n;
    clock_getttime(CLOCK_MONOTONIC, &amp;ts);
    n = (uint64_t) ts.tv_sec * 1000000 + ts.tv_nsec / 1000;
    msec = t &gt; n ? (int) ((t - n + 999) / 1000) : 0;
  }

  pollfd.fd = sd_journal_get_fd(j);
  pollfd.events = sd_journal_get_events(j);
  poll(&amp;pollfd, 1, msec);
  return sd_journal_process(j);
}</pre></div><div class="refsect1"><a name="idm139781232945840"></a><h2 id="See Also">See Also<a class="headerlink" title="Permalink to this headline" href="#See%20Also">¶</a></h2><p>
      <a href="systemd.html"><span class="citerefentry"><span class="refentrytitle">systemd</span>(1)</span></a>,
      <a href="sd-journal.html"><span class="citerefentry"><span class="refentrytitle">sd-journal</span>(3)</span></a>,
      <a href="sd_journal_open.html"><span class="citerefentry"><span class="refentrytitle">sd_journal_open</span>(3)</span></a>,
      <a href="sd_journal_next.html"><span class="citerefentry"><span class="refentrytitle">sd_journal_next</span>(3)</span></a>,
      <a href="http://man7.org/linux/man-pages/man2/poll.2.html"><span class="citerefentry"><span class="refentrytitle">poll</span>(2)</span></a>,
      <a href="http://man7.org/linux/man-pages/man2/clock_gettime.2.html"><span class="citerefentry"><span class="refentrytitle">clock_gettime</span>(2)</span></a>
    </p></div></div></body></html>
Commit	Line	Data
663996b3 MS	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>·
e3bff60a MP	22	<a href="../libudev/index.html">gudev </a><span style="float:right">systemd 220</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
e3bff60a MP	23	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="idm139781237630992"></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 a file
e735f4d4 MP	24	descriptor that may be asynchronously polled in an external event
	25	loop and is signaled as soon as the journal changes, because new
	26	entries or files were added, rotation took place, or files have
	27	been deleted, and similar. The file descriptor is suitable for
	28	usage in
	29	<a href="http://man7.org/linux/man-pages/man2/poll.2.html"><span class="citerefentry"><span class="refentrytitle">poll</span>(2)</span></a>.
	30	Use <code class="function">sd_journal_get_events()</code> for an events
	31	mask to watch for. The call takes one argument: the journal
	32	context object. Note that not all file systems are capable of
	33	generating the necessary events for wakeups from this file
	34	descriptor for changes to be noticed immediately. In particular
	35	network files systems do not generate suitable file change events
	36	in all cases. Cases like this can be detected with
	37	<code class="function">sd_journal_reliable_fd()</code>, below.
	38	<code class="function">sd_journal_get_timeout()</code> will ensure in these
	39	cases that wake-ups happen frequently enough for changes to be
	40	noticed, although with a certain latency.</p><p><code class="function">sd_journal_get_events()</code> will return the
	41	<code class="function">poll()</code> mask to wait for. This function will
	42	return a combination of <code class="constant">POLLIN</code> and
	43	<code class="constant">POLLOUT</code> and similar to fill into the
	44	"<code class="literal">.events</code>" field of <code class="varname">struct
	45	pollfd</code>.</p><p><code class="function">sd_journal_get_timeout()</code> will return a
	46	timeout value for usage in <code class="function">poll()</code>. This
	47	returns a value in microseconds since the epoch of
	48	<code class="constant">CLOCK_MONOTONIC</code> for timing out
	49	<code class="function">poll()</code> in <code class="varname">timeout_usec</code>.
	50	See
	51	<a href="http://man7.org/linux/man-pages/man2/clock_gettime.2.html"><span class="citerefentry"><span class="refentrytitle">clock_gettime</span>(2)</span></a>
	52	for details about <code class="constant">CLOCK_MONOTONIC</code>. If there
	53	is no timeout to wait for, this will fill in <code class="constant">(uint64_t)
	54	-1</code> instead. Note that <code class="function">poll()</code> takes
	55	a relative timeout in milliseconds rather than an absolute timeout
	56	in microseconds. To convert the absolute 'us' timeout into
	57	relative 'ms', use code like the following:</p><pre class="programlisting">uint64_t t;
663996b3 MS	58	int msec;
	59	sd_journal_get_timeout(m, &t);
	60	if (t == (uint64_t) -1)
e735f4d4	61	msec = -1;
663996b3	62	else {
e735f4d4 MP	63	struct timespec ts;
	64	uint64_t n;
	65	clock_getttime(CLOCK_MONOTONIC, &ts);
	66	n = (uint64_t) ts.tv_sec * 1000000 + ts.tv_nsec / 1000;
	67	msec = t > n ? (int) ((t - n + 999) / 1000) : 0;
	68	}</pre><p>The code above does not do any error checking for brevity's
	69	sake. The calculated <code class="varname">msec</code> integer can be passed
	70	directly as <code class="function">poll()</code>'s timeout
	71	parameter.</p><p>After each <code class="function">poll()</code> wake-up
	72	<code class="function">sd_journal_process()</code> needs to be called to
	73	process events. This call will also indicate what kind of change
	74	has been detected (see below; note that spurious wake-ups are
	75	possible).</p><p>A synchronous alternative for using
	76	<code class="function">sd_journal_get_fd()</code>,
	77	<code class="function">sd_journal_get_events()</code>,
	78	<code class="function">sd_journal_get_timeout()</code> and
	79	<code class="function">sd_journal_process()</code> is
	80	<code class="function">sd_journal_wait()</code>. It will synchronously wait
	81	until the journal gets changed. The maximum time this call sleeps
	82	may be controlled with the <em class="parameter"><code>timeout_usec</code></em>
	83	parameter. Pass <code class="constant">(uint64_t) -1</code> to wait
	84	indefinitely. Internally this call simply combines
	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>,
	88	<code class="function">poll()</code> and
	89	<code class="function">sd_journal_process()</code> into one.</p><p><code class="function">sd_journal_reliable_fd()</code> may be used to
	90	check whether the wakeup events from the file descriptor returned
	91	by <code class="function">sd_journal_get_fd()</code> are known to be
	92	immediately triggered. On certain file systems where file change
	93	events from the OS are not available (such as NFS) changes need to
	94	be polled for repeatedly, and hence are detected only with a
	95	certain latency. This call will return a positive value if the
	96	journal changes are detected immediately and zero when they need
	97	to be polled for and hence might be noticed only with a certain
	98	latency. Note that there's usually no need to invoke this function
	99	directly as <code class="function">sd_journal_get_timeout()</code> on these
e3bff60a	100	file systems will ask for timeouts explicitly anyway.</p></div><div class="refsect1"><a name="idm139781237699632"></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 a valid
e735f4d4 MP	101	file descriptor on success or a negative errno-style error
	102	code.</p><p><code class="function">sd_journal_get_events()</code> returns a
	103	combination of <code class="constant">POLLIN</code>,
	104	<code class="constant">POLLOUT</code> and suchlike on success or a negative
	105	errno-style error code.</p><p><code class="function">sd_journal_reliable_fd()</code> returns a
	106	positive integer if the file descriptor returned by
	107	<code class="function">sd_journal_get_fd()</code> will generate wake-ups
	108	immediately for all journal changes. Returns 0 if there might be a
	109	latency involved.</p><p><code class="function">sd_journal_process()</code> and
	110	<code class="function">sd_journal_wait()</code> return one of
	111	<code class="constant">SD_JOURNAL_NOP</code>,
	112	<code class="constant">SD_JOURNAL_APPEND</code> or
	113	<code class="constant">SD_JOURNAL_INVALIDATE</code> on success or a
	114	negative errno-style error code. If
	115	<code class="constant">SD_JOURNAL_NOP</code> is returned, the journal did
	116	not change since the last invocation. If
	117	<code class="constant">SD_JOURNAL_APPEND</code> is returned, new entries
	118	have been appended to the end of the journal. If
	119	<code class="constant">SD_JOURNAL_INVALIDATE</code>, journal files were
	120	added or removed (possibly due to rotation). In the latter event,
	121	live-view UIs should probably refresh their entire display, while
	122	in the case of <code class="constant">SD_JOURNAL_APPEND</code>, it is
	123	sufficient to simply continue reading at the previous end of the
e3bff60a	124	journal.</p></div><div class="refsect1"><a name="idm139781232957536"></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>,
e735f4d4 MP	125	<code class="function">sd_journal_get_events()</code>,
	126	<code class="function">sd_journal_reliable_fd()</code>,
	127	<code class="function">sd_journal_process()</code> and
	128	<code class="function">sd_journal_wait()</code> interfaces are available as
	129	a shared library, which can be compiled and linked to with the
	130	<code class="constant">libsystemd</code> <a href="http://linux.die.net/man/1/pkg-config"><span class="citerefentry"><span class="refentrytitle">pkg-config</span>(1)</span></a>
e3bff60a	131	file.</p></div><div class="refsect1"><a name="idm139781232951760"></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
e735f4d4	132	changes:</p><pre class="programlisting">#include <stdio.h>
663996b3 MS	133	#include <string.h>
	134	#include <systemd/sd-journal.h>
	135
	136	int main(int argc, char *argv[]) {
e735f4d4 MP	137	int r;
	138	sd_journal *j;
	139	r = sd_journal_open(&j, SD_JOURNAL_LOCAL_ONLY);
	140	if (r < 0) {
	141	fprintf(stderr, "Failed to open journal: %s\n", strerror(-r));
	142	return 1;
	143	}
	144	for (;;) {
	145	const void *d;
	146	size_t l;
	147	r = sd_journal_next(j);
	148	if (r < 0) {
	149	fprintf(stderr, "Failed to iterate to next entry: %s\n", strerror(-r));
	150	break;
	151	}
	152	if (r == 0) {
	153	/* Reached the end, let's wait for changes, and try again */
	154	r = sd_journal_wait(j, (uint64_t) -1);
	155	if (r < 0) {
	156	fprintf(stderr, "Failed to wait for changes: %s\n", strerror(-r));
	157	break;
	158	}
	159	continue;
	160	}
	161	r = sd_journal_get_data(j, "MESSAGE", &d, &l);
	162	if (r < 0) {
	163	fprintf(stderr, "Failed to read message field: %s\n", strerror(-r));
	164	continue;
	165	}
	166	printf("%.s\n", (int) l, (const char) d);
	167	}
	168	sd_journal_close(j);
	169	return 0;
663996b3	170	}</pre><p>Waiting with <code class="function">poll()</code> (this
e735f4d4 MP	171	example lacks all error checking for the sake of
e735f4d4 MP	172	simplicity):</p><pre class="programlisting">#include <poll.h>
663996b3 MS	173	#include <systemd/sd-journal.h>
	174
	175	int wait_for_changes(sd_journal *j) {
e735f4d4 MP	176	struct pollfd pollfd;
e735f4d4 MP	177	int msec;
663996b3	178
e735f4d4 MP	179	sd_journal_get_timeout(m, &t);
	180	if (t == (uint64_t) -1)
	181	msec = -1;
	182	else {
	183	struct timespec ts;
	184	uint64_t n;
	185	clock_getttime(CLOCK_MONOTONIC, &ts);
	186	n = (uint64_t) ts.tv_sec * 1000000 + ts.tv_nsec / 1000;
	187	msec = t > n ? (int) ((t - n + 999) / 1000) : 0;
	188	}
663996b3	189
e735f4d4 MP	190	pollfd.fd = sd_journal_get_fd(j);
	191	pollfd.events = sd_journal_get_events(j);
	192	poll(&pollfd, 1, msec);
	193	return sd_journal_process(j);
e3bff60a	194	}</pre></div><div class="refsect1"><a name="idm139781232945840"></a><h2 id="See Also">See Also<a class="headerlink" title="Permalink to this headline" href="#See%20Also">¶</a></h2><p>
e735f4d4 MP	195	<a href="systemd.html"><span class="citerefentry"><span class="refentrytitle">systemd</span>(1)</span></a>,
	196	<a href="sd-journal.html"><span class="citerefentry"><span class="refentrytitle">sd-journal</span>(3)</span></a>,
	197	<a href="sd_journal_open.html"><span class="citerefentry"><span class="refentrytitle">sd_journal_open</span>(3)</span></a>,
	198	<a href="sd_journal_next.html"><span class="citerefentry"><span class="refentrytitle">sd_journal_next</span>(3)</span></a>,
	199	<a href="http://man7.org/linux/man-pages/man2/poll.2.html"><span class="citerefentry"><span class="refentrytitle">poll</span>(2)</span></a>,
	200	<a href="http://man7.org/linux/man-pages/man2/clock_gettime.2.html"><span class="citerefentry"><span class="refentrytitle">clock_gettime</span>(2)</span></a>
	201	</p></div></div></body></html>