man: add notes about thread safety of sd_journal_* functions

Fixes #4056.

diff --git a/man/sd-journal.xml b/man/sd-journal.xml
index 936a83acf716a85279c3a82376164c674017ce6d..0f4b3e8eeaa0a8e8989458b03a07b9a79c40bff7 100644 (file)
--- a/man/sd-journal.xml
+++ b/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>

diff --git a/man/sd_journal_add_match.xml b/man/sd_journal_add_match.xml
index 98415d53fd16f6fbcde1ce3c5c3e0897d8ef4b1d..7c64329aed8246c3d022bee92a6f053571e589cd 100644 (file)
--- a/man/sd_journal_add_match.xml
+++ b/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

diff --git a/man/sd_journal_enumerate_fields.xml b/man/sd_journal_enumerate_fields.xml
index fa5884106b720d53d23e8f28b249177a74b9e0b9..bc2c21ed4b04bf3439a1a465c0d07b63a3e09386 100644 (file)
--- a/man/sd_journal_enumerate_fields.xml
+++ b/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

diff --git a/man/sd_journal_get_catalog.xml b/man/sd_journal_get_catalog.xml
index c19eb11b20f8ac69707e0128944166d514084240..35ec46f63e542d41b78f103a8b4537de47833da2 100644 (file)
--- a/man/sd_journal_get_catalog.xml
+++ b/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

diff --git a/man/sd_journal_get_cursor.xml b/man/sd_journal_get_cursor.xml
index a400d8b1b5e5fa33edd5ce0767c87291f5c75cff..b7aa05f8b2bf448a70725d80ab77c62c5b72b69d 100644 (file)
--- a/man/sd_journal_get_cursor.xml
+++ b/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

diff --git a/man/sd_journal_get_cutoff_realtime_usec.xml b/man/sd_journal_get_cutoff_realtime_usec.xml
index 23e7cc65e879546bd08c7cbe7ba66b4362623f47..0950e11b4451f5e13939305ca8a53374da2899ed 100644 (file)
--- a/man/sd_journal_get_cutoff_realtime_usec.xml
+++ b/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>

diff --git a/man/sd_journal_get_usage.xml b/man/sd_journal_get_usage.xml
index 72c804d8345552c351890083a4dce45effe9e026..06b0ff534d99a25ca5313400f189ab8b04a4ac89 100644 (file)
--- a/man/sd_journal_get_usage.xml
+++ b/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

diff --git a/man/sd_journal_has_runtime_files.xml b/man/sd_journal_has_runtime_files.xml
index 237e649206de2ff7093295098c9cc952218a01ea..3f6d56ca7743759de15f5382d4263f4086758152 100644 (file)
--- a/man/sd_journal_has_runtime_files.xml
+++ b/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>

diff --git a/man/sd_journal_next.xml b/man/sd_journal_next.xml
index 115fe26661cc1b003be1ef081a15f1d5827b9e28..7c385de2600f91d1385866e0a7d4f3570793b779 100644 (file)
--- a/man/sd_journal_next.xml
+++ b/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

diff --git a/man/sd_journal_open.xml b/man/sd_journal_open.xml
index 74e67023b5913b6dbb254086918ab2b9503eddb4..25b3048f2edd80f7c8b242ca54efb02e3b6c4eb2 100644 (file)
--- a/man/sd_journal_open.xml
+++ b/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

diff --git a/man/sd_journal_print.xml b/man/sd_journal_print.xml
index 76542527fcd46e3bccf571bc93cf56bcc475d73f..2d8dd635aa071572378e5aed61fa8f120c6b8d26 100644 (file)
--- a/man/sd_journal_print.xml
+++ b/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>
 

diff --git a/man/sd_journal_query_unique.xml b/man/sd_journal_query_unique.xml
index dbff55c1053f20c27d03117b8f95667830c68d91..d7a41a039c252486017013f5c87438b7e8a76009 100644 (file)
--- a/man/sd_journal_query_unique.xml
+++ b/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

diff --git a/man/sd_journal_seek_head.xml b/man/sd_journal_seek_head.xml
index d74c2d5bbc6ea26be066ac3ca591f74469ecc52c..985073496cbef4795a08efec1d4805ca4efc7300 100644 (file)
--- a/man/sd_journal_seek_head.xml
+++ b/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>,

diff --git a/man/sd_journal_stream_fd.xml b/man/sd_journal_stream_fd.xml
index 2ea7731b483f9f900a653a2dc33a0dd471cfc169..226298ae1bf7ddc9dbdf25a99af1073d90ce28e4 100644 (file)
--- a/man/sd_journal_stream_fd.xml
+++ b/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