The prohibition to move libsystemd objects between threads was added in
64a7ef8bc0 ('man: be more explicit about thread
safety of sd_journal'). At the time, this was valid, because we were using the
mempool for allocation and it apparently didn't handle access from different
threads. Sadlly, the commit links to a bugzilla entry referenced in the commit
is not publicly visible anymore, so the details are murky. But we stopped using
the mempool in a5d8835c78 ('mempool: only enable
mempool use when linked to libsystemd-shared.so'), with subsequent followup in
b01f31954f ('Turn mempool_enabled() into a weak
symbol'). The restriction added in the man page is not necessary since then.
The text in the man page was arguably incorrect in calling the code
"thread-agnostic". If the code does not support being touched from threads at
all and has global state to tied to the main thread, it is not "agnostic", but
just doesn't support threads.
(I'm looking into https://github.com/systemd/python-systemd/issues/143, and
with the current scheme, the python-systemd module and all python code using
libsystemd would be very hard to use. With the change to free-threaded python
in python3.13, i.e. the replacement of single Global Interpreter Lock by
locking on individual objects, this limitation would become even more
constraining.)
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().
The "include" files had type "book" for some raeason. I don't think this
is meaningful. Let's just use the same everywhere.
$ perl -i -0pe 's^..DOCTYPE (book|refentry) PUBLIC "-//OASIS//DTD DocBook XML V4.[25]//EN"\s+"http^<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"\n "http^gms' man/*.xml
No need to waste space, and uniformity is good.
$ perl -i -0pe 's|\n+<!--\s*SPDX-License-Identifier: LGPL-2.1..\s*-->|\n<!-- SPDX-License-Identifier: LGPL-2.1+ -->|gms' man/*.xml
Triggered by https://bugzilla.redhat.com/show_bug.cgi?id=1609349
This adds two generic paragaphs we include via xinclude. One is the
"strict" version, which contains wording saying that we are thread
agnostic and what that means. And the other is the "safe" version, for
the cases we provide fully safety.
Let's then change most man pages to use either of these generic
paragraphs. With one exception: man/sd_journal_get_catalog.xml contains
both kinds of function, we hence use manual wording.
