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