verify: use manager_load_startable_unit_or_warn() to load units for verification

[thirdparty/systemd.git] / man / sd_journal_get_fd.xml

diff --git a/man/sd_journal_get_fd.xml b/man/sd_journal_get_fd.xml
index 51dcb1aeebfcc1e54e8809a9690db262f933c7a6..f51fbc34152dcbcd28b167d68981210438e098f4 100644 (file)
--- a/man/sd_journal_get_fd.xml
+++ b/man/sd_journal_get_fd.xml
@@ -1,11 +1,10 @@
 <?xml version='1.0'?> <!--*-nxml-*-->
 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
-  "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
-<!ENTITY % entities SYSTEM "custom-entities.ent" >
-%entities;
-]>
+  "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
 
 <!--
+  SPDX-License-Identifier: LGPL-2.1+
+
   This file is part of systemd.
 
   Copyright 2012 Lennart Poettering
@@ -24,7 +23,7 @@
   along with systemd; If not, see <http://www.gnu.org/licenses/>.
 -->
 
-<refentry id="sd_journal_get_fd">
+<refentry id="sd_journal_get_fd" xmlns:xi="http://www.w3.org/2001/XInclude">
 
   <refentryinfo>
     <title>sd_journal_get_fd</title>
@@ -149,7 +148,7 @@ if (t == (uint64_t) -1)
 else {
   struct timespec ts;
   uint64_t n;
-  clock_getttime(CLOCK_MONOTONIC, &amp;ts);
+  clock_gettime(CLOCK_MONOTONIC, &amp;ts);
   n = (uint64_t) ts.tv_sec * 1000000 + ts.tv_nsec / 1000;
   msec = t > n ? (int) ((t - n + 999) / 1000) : 0;
 }</programlisting>
@@ -190,7 +189,7 @@ else {
     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
+    latency. Note that there is usually no need to invoke this function
     directly as <function>sd_journal_get_timeout()</function> on these
     file systems will ask for timeouts explicitly anyway.</para>
   </refsect1>
@@ -231,6 +230,20 @@ else {
     journal.</para>
   </refsect1>
 
+  <refsect1>
+    <title>Signal safety</title>
+
+    <para>In general, <function>sd_journal_get_fd()</function>, <function>sd_journal_get_events()</function>, and
+    <function>sd_journal_get_timeout()</function> are <emphasis>not</emphasis> "async signal safe" in the meaning of
+    <citerefentry
+    project='man-pages'><refentrytitle>signal-safety</refentrytitle><manvolnum>7</manvolnum></citerefentry>.
+    Nevertheless, only the first call to any of those three functions performs unsafe operations, so subsequent calls
+    <emphasis>are</emphasis> safe.</para>
+
+    <para><function>sd_journal_process()</function> and <function>sd_journal_wait()</function> are not
+    safe. <function>sd_journal_reliable_fd()</function> is safe.</para>
+  </refsect1>
+
   <refsect1>
     <title>Notes</title>
 
@@ -250,73 +263,13 @@ else {
     <para>Iterating through the journal, in a live view tracking all
     changes:</para>
 
-    <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;
-}</programlisting>
+    <programlisting><xi:include href="journal-iterate-wait.c" parse="text" /></programlisting>
 
     <para>Waiting with <function>poll()</function> (this
     example lacks all error checking for the sake of
     simplicity):</para>
 
-    <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 > 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);
-}</programlisting>
+    <programlisting><xi:include href="journal-iterate-poll.c" parse="text" /></programlisting>
   </refsect1>
 
   <refsect1>