man: add notes about thread safety of sd_journal_* functions

Fixes #4056.

man/sd-journal.xml

@@ -98,6 +98,21 @@
     tool.</para>
   </refsect1>
 
+  <refsect1>
+    <title>Thread safety</title>
+
+    <para>Functions that operate on the <structname>sd_journal</structname> object are thread
+    agnostic — given <structname>sd_journal</structname> pointer may only be used from one thread at
+    a time, but multiple threads may use multiple such objects safely. Other functions —
+    those that are used to send entries to the journal, like
+    <citerefentry><refentrytitle>sd_journal_print</refentrytitle><manvolnum>3</manvolnum></citerefentry>
+    and similar, or those that are used to retrieve global information like
+    <citerefentry><refentrytitle>sd_journal_stream_fd</refentrytitle><manvolnum>3</manvolnum></citerefentry>
+    and
+    <citerefentry><refentrytitle>sd_journal_get_catalog_for_message_id</refentrytitle><manvolnum>3</manvolnum></citerefentry>
+    — are thread-safe and may be called from multiple threads in parallel.</para>
+  </refsect1>
+
   <xi:include href="libsystemd-pkgconfig.xml" />
 
   <refsect1>

man/sd_journal_add_match.xml

@@ -168,6 +168,9 @@
   <refsect1>
     <title>Notes</title>
 
+    <para>All functions listed here are thread-agnostic and only a single thread may operate
+    on a given <structname>sd_journal</structname> object.</para>
+
     <para>The <function>sd_journal_add_match()</function>,
     <function>sd_journal_add_disjunction()</function>,
     <function>sd_journal_add_conjunction()</function> and

man/sd_journal_enumerate_fields.xml

@@ -110,6 +110,9 @@
   <refsect1>
     <title>Notes</title>
 
+    <para>All functions listed here are thread-agnostic and only a single thread may operate
+    on a given <structname>sd_journal</structname> object.</para>
+
     <para>The <function>sd_journal_enumerate_fields()</function> and <function>sd_journal_restart_fields()</function>
     interfaces are available as a shared library, which can be compiled and linked to with the
     <constant>libsystemd</constant> <citerefentry

man/sd_journal_get_catalog.xml

@@ -112,6 +112,10 @@
   <refsect1>
     <title>Notes</title>
 
+    <para>Function <function>sd_journal_get_catalog()</function> is thread-agnostic and only a
+    single thread may operate on a given <structname>sd_journal</structname> object. Function
+    <function>sd_journal_get_catalog_for_message_id() is thread-safe.</function></para>
+
     <para>The <function>sd_journal_get_catalog()</function> and
     <function>sd_journal_get_catalog_for_message_id()</function>
     interfaces are available as a shared library, which can be

man/sd_journal_get_cursor.xml

@@ -122,6 +122,9 @@
   <refsect1>
     <title>Notes</title>
 
+    <para>All functions listed here are thread-agnostic and only a single thread may operate
+    on a given <structname>sd_journal</structname> object.</para>
+
     <para>The <function>sd_journal_get_cursor()</function> and
     <function>sd_journal_test_cursor()</function> interfaces are
     available as a shared library, which can be compiled and linked to

man/sd_journal_get_cutoff_realtime_usec.xml

@@ -120,6 +120,9 @@
   <refsect1>
     <title>Notes</title>
 
+    <para>All functions listed here are thread-agnostic and only a single thread may operate
+    on a given <structname>sd_journal</structname> object.</para>
+
     <para>The
     <function>sd_journal_get_cutoff_realtime_usec()</function> and
     <function>sd_journal_get_cutoff_monotonic_usec()</function>

man/sd_journal_get_usage.xml

@@ -80,6 +80,9 @@
   <refsect1>
     <title>Notes</title>
 
+    <para>All functions listed here are thread-agnostic and only a single thread may operate
+    on a given <structname>sd_journal</structname> object.</para>
+
     <para>The <function>sd_journal_get_usage()</function> interface is
     available as a shared library, which can be compiled and linked to
     with the

man/sd_journal_has_runtime_files.xml

@@ -85,6 +85,18 @@
     </para>
   </refsect1>
 
+  <refsect1>
+    <title>Notes</title>
+
+    <para>All functions listed here are thread-agnostic and only a single thread may operate
+    on a given <structname>sd_journal</structname> object.</para>
+
+    <para>Functions listed here are available as a shared library, which can be compiled and linked
+    to with the <constant>libsystemd</constant> <citerefentry
+    project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry>
+    file.</para>
+  </refsect1>
+
   <refsect1>
     <title>See Also</title>
     <para>

man/sd_journal_next.xml

@@ -146,6 +146,9 @@
   <refsect1>
     <title>Notes</title>
 
+    <para>All functions listed here are thread-agnostic and only a single thread may operate
+    on a given <structname>sd_journal</structname> object.</para>
+
     <para>The <function>sd_journal_next()</function>,
     <function>sd_journal_previous()</function>,
     <function>sd_journal_next_skip()</function> and

man/sd_journal_open.xml

@@ -208,6 +208,9 @@
   <refsect1>
     <title>Notes</title>
 
+    <para>All functions listed here are thread-agnostic and only a single thread may operate
+    on a given <structname>sd_journal</structname> object.</para>
+
     <para>The <function>sd_journal_open()</function>,
     <function>sd_journal_open_directory()</function> and
     <function>sd_journal_close()</function> interfaces are available

man/sd_journal_print.xml

@@ -201,9 +201,10 @@ sd_journal_send("MESSAGE=Hello World, this is PID %lu!", (unsigned long) getpid(
   </refsect1>
 
   <refsect1>
-    <title>Async signal safety</title>
-    <para><function>sd_journal_sendv()</function> is "async signal
-    safe" in the meaning of
+    <title>Thread safety</title>
+    <para>All functions listed here are thread-safe and may be called in parallel from multiple threads.</para>
+
+    <para><function>sd_journal_sendv()</function> is "async signal safe" in the meaning of
     <citerefentry project='man-pages'><refentrytitle>signal</refentrytitle><manvolnum>7</manvolnum></citerefentry>.
     </para>
 

man/sd_journal_query_unique.xml

@@ -150,6 +150,9 @@
   <refsect1>
     <title>Notes</title>
 
+    <para>All functions listed here are thread-agnostic and only a single thread may operate
+    on a given <structname>sd_journal</structname> object.</para>
+
     <para>The <function>sd_journal_query_unique()</function>,
     <function>sd_journal_enumerate_unique()</function> and
     <function>sd_journal_restart_unique()</function> interfaces are

man/sd_journal_seek_head.xml

@@ -144,6 +144,9 @@
   <refsect1>
     <title>Notes</title>
 
+    <para>All functions listed here are thread-agnostic and only a single thread may operate
+    on a given <structname>sd_journal</structname> object.</para>
+
     <para>The <function>sd_journal_seek_head()</function>,
     <function>sd_journal_seek_tail()</function>,
     <function>sd_journal_seek_monotonic_usec()</function>,

man/sd_journal_stream_fd.xml

@@ -104,6 +104,10 @@
   <refsect1>
     <title>Notes</title>
 
+    <para>Function <function>sd_journal_stream_fd()</function> is thread-safe and may be be called
+    from multiple threads. All calls will return the same file descriptor, although temporarily
+    multiple file descriptors may be open.</para>
+
     <para>The <function>sd_journal_stream_fd()</function> interface is
     available as a shared library, which can be compiled and linked to
     with the