man: add mention that libsystemd uses getenv()

See #26688: getenv() is not thread-safe, and could a possible source of
problems when a multi-threaded program calls setenv()/putenv()/unsetenv() in
parallel. It is not possible to avoid getenv() calls in general, since $PATH,
$LANG, $SHELL, $USER, $HOME, $TZ may need to be accessed at any time.
Add a warning to our docs so that people are aware of the issue.

Closes #26688. (Real fixes will need to be in glibc and gnome-shell or other
programs.)

The text is added to threads-aware.xml to be included in various places. By
including it in libsystemd-pkgconfig.xml, it is automatically added to all sd-*
pages. The text is also included explicitly in pages for a few other functions
which are call getenv().

diff --git a/man/libsystemd-pkgconfig.xml b/man/libsystemd-pkgconfig.xml
index e3b0634c9f09ecb62492555a4f133e3475b2c5a5..3d228707395415efa154958cebdfa67667f6dd53 100644 (file)
--- a/man/libsystemd-pkgconfig.xml
+++ b/man/libsystemd-pkgconfig.xml
@@ -3,11 +3,14 @@
   "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
 <!-- SPDX-License-Identifier: LGPL-2.1-or-later -->
 
-<refsect1>
+<refsect1 xmlns:xi="http://www.w3.org/2001/XInclude">
+
   <title>Notes</title>
 
-  <para id='pkgconfig-text'>These APIs are implemented as a shared
-  library, which can be compiled and linked to with the
+  <para id='pkgconfig-text'>Functions described here are available as a shared
+  library, which can be compiled against and linked to with the
   <constant>libsystemd</constant> <citerefentry project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry>
   file.</para>
+
+  <xi:include href="threads-aware.xml" xpointer="getenv"/>
 </refsect1>

diff --git a/man/libudev.xml b/man/libudev.xml
index c2a42cbfd46e08974b5f3f59f45fadad0a101162..684bd47fcdbd54acd5dfde4ae0dd52894e1d8e73 100644 (file)
--- a/man/libudev.xml
+++ b/man/libudev.xml
@@ -50,6 +50,7 @@
     a udev context.</para>
 
     <xi:include href="threads-aware.xml" xpointer="strict"/>
+    <xi:include href="threads-aware.xml" xpointer="getenv"/>
 
     <para>To introspect a local device on a system, a udev device
     object can be created via

diff --git a/man/sd_bus_add_match.xml b/man/sd_bus_add_match.xml
index 429a2fd412ad577a88ecada4a6e9bf8297785c3e..1ab1c0f5171f9db985c3e683c9fd223aac9ade1b 100644 (file)
--- a/man/sd_bus_add_match.xml
+++ b/man/sd_bus_add_match.xml
@@ -151,11 +151,7 @@
     </para>
   </refsect1>
 
-  <refsect1>
-    <title>Notes</title>
-
-    <xi:include href="libsystemd-pkgconfig.xml" xpointer="pkgconfig-text"/>
-  </refsect1>
+  <xi:include href="libsystemd-pkgconfig.xml" />
 
   <refsect1>
     <title>See Also</title>

diff --git a/man/sd_listen_fds.xml b/man/sd_listen_fds.xml
index 9e0be7fbf7fadf2c81c2c2c7dabc53d42360d575..e45907075c598a74e216ca6a1e3674bba982c9c3 100644 (file)
--- a/man/sd_listen_fds.xml
+++ b/man/sd_listen_fds.xml
@@ -183,6 +183,7 @@
     <title>Notes</title>
 
     <xi:include href="libsystemd-pkgconfig.xml" xpointer="pkgconfig-text"/>
+    <xi:include href="threads-aware.xml" xpointer="getenv"/>
 
     <para>Internally, <function>sd_listen_fds()</function> checks
     whether the <varname>$LISTEN_PID</varname> environment variable

diff --git a/man/sd_notify.xml b/man/sd_notify.xml
index 8ef1c507caceab86951007e08eef8f5f725ce117..8a0911286570d2c8bb463cdc61388873da17fc1b 100644 (file)
--- a/man/sd_notify.xml
+++ b/man/sd_notify.xml
@@ -378,6 +378,7 @@
     <title>Notes</title>
 
     <xi:include href="libsystemd-pkgconfig.xml" xpointer="pkgconfig-text"/>
+    <xi:include href="threads-aware.xml" xpointer="getenv"/>
 
     <para>These functions send a single datagram with the
     state string as payload to the socket referenced in the

diff --git a/man/sd_watchdog_enabled.xml b/man/sd_watchdog_enabled.xml
index 1abc2f805164c713b94fd58e7828f4706af90938..b4a59f2ad10e6d864474ced35cf34d5bf04a91cb 100644 (file)
--- a/man/sd_watchdog_enabled.xml
+++ b/man/sd_watchdog_enabled.xml
@@ -93,6 +93,7 @@
     <title>Notes</title>
 
     <xi:include href="libsystemd-pkgconfig.xml" xpointer="pkgconfig-text"/>
+    <xi:include href="threads-aware.xml" xpointer="getenv"/>
 
     <para>Internally, this function parses the
     <varname>$WATCHDOG_PID</varname> and

diff --git a/man/threads-aware.xml b/man/threads-aware.xml
index fb38d07e1a8382fd5123f192a02e2fe9da52fa05..442e45bbbbadf9a56785d8991aba5847a3aa2c63 100644 (file)
--- a/man/threads-aware.xml
+++ b/man/threads-aware.xml
@@ -12,4 +12,12 @@ from any other, even if locking is used to ensure these threads don't operate on
 
 <para id="safe">All functions listed here are thread-safe and may be called in parallel from multiple threads.</para>
 
+<para id='getenv'>The code described here uses
+<citerefentry project='man-pages'><refentrytitle>getenv</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+which is declared to be not multi-thread-safe. This means that the code calling the functions described
+here must not call
+<citerefentry project='man-pages'><refentrytitle>setenv</refentrytitle><manvolnum>3</manvolnum></citerefentry>
+from a parallel thread. It is recommended to only do calls to <function>setenv()</function>
+from an early phase of the program when no other threads have been started.</para>
+
 </refsect1>