[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 217</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="idm214177185680"></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="idm214177145424"></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="idm214172223728"></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="idm214172217904"></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;sys/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="idm214172211280"></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>·
5eef597e MP	22	<a href="../libudev/index.html">gudev </a><span style="float:right">systemd 217</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
5eef597e 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="idm214177185680"></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
663996b3 MS	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
5eef597e	30	<a href="http://man7.org/linux/man-pages/man2/poll.2.html"><span class="citerefentry"><span class="refentrytitle">poll</span>(2)</span></a>. Use
663996b3 MS	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
14228c0d MB	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
5eef597e	56	<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>
663996b3	57	for details about
14228c0d MB	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
663996b3 MS	61	<code class="function">poll()</code> takes a relative timeout
663996b3 MS	62	in milliseconds rather than an absolute timeout in
14228c0d MB	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;
663996b3 MS	66	int msec;
	67	sd_journal_get_timeout(m, &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, &ts);
	74	n = (uint64_t) ts.tv_sec * 1000000 + ts.tv_nsec / 1000;
	75	msec = t > n ? (int) ((t - n + 999) / 1000) : 0;
	76	}</pre><p>The code above does not do any error checking
14228c0d	77	for brevity's sake. The calculated <code class="varname">msec</code>
663996b3 MS	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>
14228c0d	93	parameter. Pass <code class="constant">(uint64_t) -1</code> to
663996b3 MS	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
5eef597e	115	anyway.</p></div><div class="refsect1"><a name="idm214177145424"></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
663996b3 MS	116	a valid file descriptor on success or a negative
663996b3 MS	117	errno-style error code.</p><p><code class="function">sd_journal_get_events()</code>
14228c0d MB	118	returns a combination of <code class="constant">POLLIN</code>,
14228c0d MB	119	<code class="constant">POLLOUT</code> and suchlike on success or
663996b3 MS	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
14228c0d MB	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
663996b3	130	a negative errno-style error code. If
14228c0d MB	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
663996b3	134	entries have been appended to the end of the
14228c0d	135	journal. If <code class="constant">SD_JOURNAL_INVALIDATE</code>,
663996b3	136	journal files were added or removed (possibly due to
14228c0d MB	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
663996b3	140	sufficient to simply continue reading at the previous
5eef597e	141	end of the journal.</p></div><div class="refsect1"><a name="idm214172223728"></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>,
663996b3 MS	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
60f067b4	146	available as a shared library, which can be compiled and
663996b3	147	linked to with the
5eef597e MP	148	<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>
5eef597e MP	149	file.</p></div><div class="refsect1"><a name="idm214172217904"></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 <stdio.h>
663996b3 MS	150	#include <string.h>
	151	#include <systemd/sd-journal.h>
	152
	153	int main(int argc, char *argv[]) {
	154	int r;
	155	sd_journal *j;
	156	r = sd_journal_open(&j, SD_JOURNAL_LOCAL_ONLY);
	157	if (r < 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 < 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 < 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", &d, &l);
	179	if (r < 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 <sys/poll.h>
	190	#include <systemd/sd-journal.h>
	191
	192	int wait_for_changes(sd_journal *j) {
	193	struct pollfd pollfd;
	194	int msec;
	195
	196	sd_journal_get_timeout(m, &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, &ts);
	203	n = (uint64_t) ts.tv_sec * 1000000 + ts.tv_nsec / 1000;
	204	msec = t > 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(&pollfd, 1, msec);
	210	return sd_journal_process(j);
5eef597e	211	}</pre></div><div class="refsect1"><a name="idm214172211280"></a><h2 id="See Also">See Also<a class="headerlink" title="Permalink to this headline" href="#See%20Also">¶</a></h2><p>
663996b3 MS	212	<a href="systemd.html"><span class="citerefentry"><span class="refentrytitle">systemd</span>(1)</span></a>,
	213	<a href="sd-journal.html"><span class="citerefentry"><span class="refentrytitle">sd-journal</span>(3)</span></a>,
	214	<a href="sd_journal_open.html"><span class="citerefentry"><span class="refentrytitle">sd_journal_open</span>(3)</span></a>,
	215	<a href="sd_journal_next.html"><span class="citerefentry"><span class="refentrytitle">sd_journal_next</span>(3)</span></a>,
5eef597e MP	216	<a href="http://man7.org/linux/man-pages/man2/poll.2.html"><span class="citerefentry"><span class="refentrytitle">poll</span>(2)</span></a>,
5eef597e MP	217	<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>
663996b3	218	</p></div></div></body></html>