From af2a7ac568af7b8ecf1002023dd9d07135c3c9c2 Mon Sep 17 00:00:00 2001
From: Daniel Baumann <daniel.baumann@progress-linux.org>
Date: Thu, 25 Apr 2024 04:54:54 +0200
Subject: Merging upstream version 255.5.

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>
---
 man/systemctl.xml | 68 +++++++++++++++++++++++++++++++++++--------------------
 1 file changed, 43 insertions(+), 25 deletions(-)

(limited to 'man/systemctl.xml')

diff --git a/man/systemctl.xml b/man/systemctl.xml
index 25b6e46..9bdd882 100644
--- a/man/systemctl.xml
+++ b/man/systemctl.xml
@@ -1318,36 +1318,49 @@ Jan 12 10:46:45 example.com bluetoothd[8900]: gatt-time-server: Input/output err
           <term><command>show-environment</command></term>
 
           <listitem>
-            <para>Dump the systemd manager environment block. This is the environment
-            block that is passed to all processes the manager spawns. The environment
-            block will be dumped in straightforward form suitable for sourcing into
-            most shells. If no special characters or whitespace is present in the variable
-            values, no escaping is performed, and the assignments have the form
-            <literal>VARIABLE=value</literal>. If whitespace or characters which have
-            special meaning to the shell are present, dollar-single-quote escaping is
-            used, and assignments have the form <literal>VARIABLE=$'value'</literal>.
-            This syntax is known to be supported by
-            <citerefentry project='die-net'><refentrytitle>bash</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
-            <citerefentry project='die-net'><refentrytitle>zsh</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
-            <citerefentry project='die-net'><refentrytitle>ksh</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
-            and
-            <citerefentry project='die-net'><refentrytitle>busybox</refentrytitle><manvolnum>1</manvolnum></citerefentry>'s
-            <citerefentry project='die-net'><refentrytitle>ash</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
-            but not
-            <citerefentry project='die-net'><refentrytitle>dash</refentrytitle><manvolnum>1</manvolnum></citerefentry>
-            or
-            <citerefentry project='die-net'><refentrytitle>fish</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
+            <para>Dump the systemd manager environment block. This is the environment block that is passed to
+            all processes the manager spawns. The environment block will be dumped in straightforward form
+            suitable for sourcing into most shells. If no special characters or whitespace is present in the
+            variable values, no escaping is performed, and the assignments have the form
+            <literal>VARIABLE=value</literal>. If whitespace or characters which have special meaning to the
+            shell are present, dollar-single-quote escaping is used, and assignments have the form
+            <literal>VARIABLE=$'value'</literal>.  This syntax is known to be supported by <citerefentry
+            project='die-net'><refentrytitle>bash</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
+            <citerefentry
+            project='die-net'><refentrytitle>zsh</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
+            <citerefentry
+            project='die-net'><refentrytitle>ksh</refentrytitle><manvolnum>1</manvolnum></citerefentry>, and
+            <citerefentry
+            project='die-net'><refentrytitle>busybox</refentrytitle><manvolnum>1</manvolnum></citerefentry>'s
+            <citerefentry
+            project='die-net'><refentrytitle>ash</refentrytitle><manvolnum>1</manvolnum></citerefentry>, but
+            not <citerefentry
+            project='die-net'><refentrytitle>dash</refentrytitle><manvolnum>1</manvolnum></citerefentry> or
+            <citerefentry
+            project='die-net'><refentrytitle>fish</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
             </para>
+
+            <para>Note that this shows the <emphasis>effective</emphasis> block, i.e. the combination of
+            environment variables configured via configuration files, environment generators and via IPC
+            (i.e. via the <command>set-environment</command> described below). At the moment a unit process
+            is forked off this combined environment block will be further combined with per-unit environment
+            variables, which are not visible in this command.</para>
           </listitem>
         </varlistentry>
         <varlistentry>
           <term><command>set-environment <replaceable>VARIABLE=VALUE</replaceable>…</command></term>
 
           <listitem>
-            <para>Set one or more systemd manager environment variables, as specified on the command
+            <para>Set one or more service manager environment variables, as specified on the command
             line. This command will fail if variable names and values do not conform to the rules listed
             above.</para>
 
+            <para>Note that this operates on an environment block separate from the environment block
+            configured from service manager configuration and environment generators. Whenever a process is
+            invoked the two blocks are combined (also incorporating any per-service environment variables),
+            and passed to it. The <command>show-environment</command> verb will show the combination of the
+            blocks, see above.</para>
+
             <xi:include href="version-info.xml" xpointer="v233"/>
           </listitem>
         </varlistentry>
@@ -1355,11 +1368,16 @@ Jan 12 10:46:45 example.com bluetoothd[8900]: gatt-time-server: Input/output err
           <term><command>unset-environment <replaceable>VARIABLE</replaceable>…</command></term>
 
           <listitem>
-            <para>Unset one or more systemd manager environment
-            variables. If only a variable name is specified, it will be
-            removed regardless of its value. If a variable and a value
-            are specified, the variable is only removed if it has the
-            specified value.</para>
+            <para>Unset one or more systemd manager environment variables. If only a variable name is
+            specified, it will be removed regardless of its value. If a variable and a value are specified,
+            the variable is only removed if it has the specified value.</para>
+
+            <para>Note that this operates on an environment block separate from the environment block
+            configured from service manager configuration and environment generators. Whenever a process is
+            invoked the two blocks are combined (also incorporating any per-service environment variables),
+            and passed to it. The <command>show-environment</command> verb will show the combination of the
+            blocks, see above. Note that this means this command cannot be used to unset environment
+            variables defined in the service manager configuration files or via generators.</para>
 
             <xi:include href="version-info.xml" xpointer="v233"/>
           </listitem>
-- 
cgit v1.2.3