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().

7 files changed, 19 insertions, 8 deletions

diff --git a/man/libsystemd-pkgconfig.xml b/man/libsystemd-pkgconfig.xml
index e3b0634c9f..3d22870739 100644
--- 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 c2a42cbfd4..684bd47fcd 100644
--- 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 429a2fd412..1ab1c0f517 100644
--- 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 9e0be7fbf7..e45907075c 100644
--- 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 8ef1c507ca..8a09112865 100644
--- 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 1abc2f8051..b4a59f2ad1 100644
--- 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 fb38d07e1a..442e45bbbb 100644
--- 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>