summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorZbigniew Jędrzejewski-Szmek <zbyszek@in.waw.pl>2016-10-15 15:24:55 -0400
committerZbigniew Jędrzejewski-Szmek <zbyszek@in.waw.pl>2016-10-15 18:38:20 -0400
commita8d46a1663c80e96508ed9bbd7c3acd55c5b4252 (patch)
treef1f809b82d19995f55519de5ed10cf5c2b26dbdd
parent74b47bbd5d4770c68e0eb448cc157414288ce60d (diff)
man: add notes about thread safety of sd_journal_* functions
Fixes #4056.
-rw-r--r--man/sd-journal.xml15
-rw-r--r--man/sd_journal_add_match.xml3
-rw-r--r--man/sd_journal_enumerate_fields.xml3
-rw-r--r--man/sd_journal_get_catalog.xml4
-rw-r--r--man/sd_journal_get_cursor.xml3
-rw-r--r--man/sd_journal_get_cutoff_realtime_usec.xml3
-rw-r--r--man/sd_journal_get_usage.xml3
-rw-r--r--man/sd_journal_has_runtime_files.xml12
-rw-r--r--man/sd_journal_next.xml3
-rw-r--r--man/sd_journal_open.xml3
-rw-r--r--man/sd_journal_print.xml7
-rw-r--r--man/sd_journal_query_unique.xml3
-rw-r--r--man/sd_journal_seek_head.xml3
-rw-r--r--man/sd_journal_stream_fd.xml4
14 files changed, 66 insertions, 3 deletions
diff --git a/man/sd-journal.xml b/man/sd-journal.xml
index 936a83acf7..0f4b3e8eea 100644
--- 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 98415d53fd..7c64329aed 100644
--- 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 fa5884106b..bc2c21ed4b 100644
--- 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 c19eb11b20..35ec46f63e 100644
--- 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 a400d8b1b5..b7aa05f8b2 100644
--- 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 23e7cc65e8..0950e11b44 100644
--- 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 72c804d834..06b0ff534d 100644
--- 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 237e649206..3f6d56ca77 100644
--- a/man/sd_journal_has_runtime_files.xml
+++ b/man/sd_journal_has_runtime_files.xml
@@ -86,6 +86,18 @@
</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>
<citerefentry><refentrytitle>sd-journal</refentrytitle><manvolnum>3</manvolnum></citerefentry>
diff --git a/man/sd_journal_next.xml b/man/sd_journal_next.xml
index 115fe26661..7c385de260 100644
--- 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 74e67023b5..25b3048f2e 100644
--- 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 76542527fc..2d8dd635aa 100644
--- 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 dbff55c105..d7a41a039c 100644
--- 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 d74c2d5bbc..985073496c 100644
--- 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 2ea7731b48..226298ae1b 100644
--- 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