From: Zbigniew Jędrzejewski-Szmek Date: Sat, 15 Oct 2016 19:24:55 +0000 (-0400) Subject: man: add notes about thread safety of sd_journal_* functions X-Git-Tag: v232~90^2~2 X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=a8d46a1663c80e96508ed9bbd7c3acd55c5b4252;p=thirdparty%2Fsystemd.git 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 936a83acf71..0f4b3e8eeaa 100644 --- a/man/sd-journal.xml +++ b/man/sd-journal.xml @@ -98,6 +98,21 @@ tool. + + Thread safety + + Functions that operate on the sd_journal object are thread + agnostic — given sd_journal 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 + sd_journal_print3 + and similar, or those that are used to retrieve global information like + sd_journal_stream_fd3 + and + sd_journal_get_catalog_for_message_id3 + — are thread-safe and may be called from multiple threads in parallel. + + diff --git a/man/sd_journal_add_match.xml b/man/sd_journal_add_match.xml index 98415d53fd1..7c64329aed8 100644 --- a/man/sd_journal_add_match.xml +++ b/man/sd_journal_add_match.xml @@ -168,6 +168,9 @@ Notes + All functions listed here are thread-agnostic and only a single thread may operate + on a given sd_journal object. + The sd_journal_add_match(), sd_journal_add_disjunction(), sd_journal_add_conjunction() and diff --git a/man/sd_journal_enumerate_fields.xml b/man/sd_journal_enumerate_fields.xml index fa5884106b7..bc2c21ed4b0 100644 --- a/man/sd_journal_enumerate_fields.xml +++ b/man/sd_journal_enumerate_fields.xml @@ -110,6 +110,9 @@ Notes + All functions listed here are thread-agnostic and only a single thread may operate + on a given sd_journal object. + The sd_journal_enumerate_fields() and sd_journal_restart_fields() interfaces are available as a shared library, which can be compiled and linked to with the libsystemd  Notes + Function sd_journal_get_catalog() is thread-agnostic and only a + single thread may operate on a given sd_journal object. Function + sd_journal_get_catalog_for_message_id() is thread-safe. + The sd_journal_get_catalog() and sd_journal_get_catalog_for_message_id() 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 a400d8b1b5e..b7aa05f8b2b 100644 --- a/man/sd_journal_get_cursor.xml +++ b/man/sd_journal_get_cursor.xml @@ -122,6 +122,9 @@ Notes + All functions listed here are thread-agnostic and only a single thread may operate + on a given sd_journal object. + The sd_journal_get_cursor() and sd_journal_test_cursor() 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 23e7cc65e87..0950e11b445 100644 --- a/man/sd_journal_get_cutoff_realtime_usec.xml +++ b/man/sd_journal_get_cutoff_realtime_usec.xml @@ -120,6 +120,9 @@ Notes + All functions listed here are thread-agnostic and only a single thread may operate + on a given sd_journal object. + The sd_journal_get_cutoff_realtime_usec() and sd_journal_get_cutoff_monotonic_usec() diff --git a/man/sd_journal_get_usage.xml b/man/sd_journal_get_usage.xml index 72c804d8345..06b0ff534d9 100644 --- a/man/sd_journal_get_usage.xml +++ b/man/sd_journal_get_usage.xml @@ -80,6 +80,9 @@ Notes + All functions listed here are thread-agnostic and only a single thread may operate + on a given sd_journal object. + The sd_journal_get_usage() 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 237e649206d..3f6d56ca774 100644 --- a/man/sd_journal_has_runtime_files.xml +++ b/man/sd_journal_has_runtime_files.xml @@ -85,6 +85,18 @@ + + Notes + + All functions listed here are thread-agnostic and only a single thread may operate + on a given sd_journal object. + + Functions listed here are available as a shared library, which can be compiled and linked + to with the libsystemd pkg-config1 + file. + + See Also diff --git a/man/sd_journal_next.xml b/man/sd_journal_next.xml index 115fe26661c..7c385de2600 100644 --- a/man/sd_journal_next.xml +++ b/man/sd_journal_next.xml @@ -146,6 +146,9 @@ Notes + All functions listed here are thread-agnostic and only a single thread may operate + on a given sd_journal object. + The sd_journal_next(), sd_journal_previous(), sd_journal_next_skip() and diff --git a/man/sd_journal_open.xml b/man/sd_journal_open.xml index 74e67023b59..25b3048f2ed 100644 --- a/man/sd_journal_open.xml +++ b/man/sd_journal_open.xml @@ -208,6 +208,9 @@ Notes + All functions listed here are thread-agnostic and only a single thread may operate + on a given sd_journal object. + The sd_journal_open(), sd_journal_open_directory() and sd_journal_close() interfaces are available diff --git a/man/sd_journal_print.xml b/man/sd_journal_print.xml index 76542527fcd..2d8dd635aa0 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( - Async signal safety - sd_journal_sendv() is "async signal - safe" in the meaning of + Thread safety + All functions listed here are thread-safe and may be called in parallel from multiple threads. + + sd_journal_sendv() is "async signal safe" in the meaning of signal7. diff --git a/man/sd_journal_query_unique.xml b/man/sd_journal_query_unique.xml index dbff55c1053..d7a41a039c2 100644 --- a/man/sd_journal_query_unique.xml +++ b/man/sd_journal_query_unique.xml @@ -150,6 +150,9 @@ Notes + All functions listed here are thread-agnostic and only a single thread may operate + on a given sd_journal object. + The sd_journal_query_unique(), sd_journal_enumerate_unique() and sd_journal_restart_unique() interfaces are diff --git a/man/sd_journal_seek_head.xml b/man/sd_journal_seek_head.xml index d74c2d5bbc6..985073496cb 100644 --- a/man/sd_journal_seek_head.xml +++ b/man/sd_journal_seek_head.xml @@ -144,6 +144,9 @@ Notes + All functions listed here are thread-agnostic and only a single thread may operate + on a given sd_journal object. + The sd_journal_seek_head(), sd_journal_seek_tail(), sd_journal_seek_monotonic_usec(), diff --git a/man/sd_journal_stream_fd.xml b/man/sd_journal_stream_fd.xml index 2ea7731b483..226298ae1bf 100644 --- a/man/sd_journal_stream_fd.xml +++ b/man/sd_journal_stream_fd.xml @@ -104,6 +104,10 @@ Notes + Function sd_journal_stream_fd() 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. + The sd_journal_stream_fd() interface is available as a shared library, which can be compiled and linked to with the