1
0
mirror of https://github.com/systemd/systemd.git synced 2024-12-22 17:35:35 +03:00

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().
This commit is contained in:
Zbigniew Jędrzejewski-Szmek 2023-03-07 20:25:58 +01:00
parent 1a87882635
commit 8c51e1520b
7 changed files with 19 additions and 8 deletions

View File

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

View File

@ -50,6 +50,7 @@
a udev context.</para> a udev context.</para>
<xi:include href="threads-aware.xml" xpointer="strict"/> <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 <para>To introspect a local device on a system, a udev device
object can be created via object can be created via

View File

@ -151,11 +151,7 @@
</para> </para>
</refsect1> </refsect1>
<refsect1> <xi:include href="libsystemd-pkgconfig.xml" />
<title>Notes</title>
<xi:include href="libsystemd-pkgconfig.xml" xpointer="pkgconfig-text"/>
</refsect1>
<refsect1> <refsect1>
<title>See Also</title> <title>See Also</title>

View File

@ -183,6 +183,7 @@
<title>Notes</title> <title>Notes</title>
<xi:include href="libsystemd-pkgconfig.xml" xpointer="pkgconfig-text"/> <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 <para>Internally, <function>sd_listen_fds()</function> checks
whether the <varname>$LISTEN_PID</varname> environment variable whether the <varname>$LISTEN_PID</varname> environment variable

View File

@ -378,6 +378,7 @@
<title>Notes</title> <title>Notes</title>
<xi:include href="libsystemd-pkgconfig.xml" xpointer="pkgconfig-text"/> <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 <para>These functions send a single datagram with the
state string as payload to the socket referenced in the state string as payload to the socket referenced in the

View File

@ -93,6 +93,7 @@
<title>Notes</title> <title>Notes</title>
<xi:include href="libsystemd-pkgconfig.xml" xpointer="pkgconfig-text"/> <xi:include href="libsystemd-pkgconfig.xml" xpointer="pkgconfig-text"/>
<xi:include href="threads-aware.xml" xpointer="getenv"/>
<para>Internally, this function parses the <para>Internally, this function parses the
<varname>$WATCHDOG_PID</varname> and <varname>$WATCHDOG_PID</varname> and

View File

@ -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="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> </refsect1>