Merging upstream version 256.

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 66 insertions, 27 deletions

diff --git a/man/systemd-run.xml b/man/systemd-run.xml
index 5be9823..e1986c1 100644
--- a/man/systemd-run.xml
+++ b/man/systemd-run.xml
@@ -1,6 +1,6 @@
 <?xml version='1.0'?>
 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
-  "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
+  "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
 <!-- SPDX-License-Identifier: LGPL-2.1-or-later -->
 
 <refentry id="systemd-run"
@@ -64,8 +64,8 @@
     other service, and thus shows up in the output of <command>systemctl list-units</command> like any other unit. It
     will run in a clean and detached execution environment, with the service manager as its parent process. In this
     mode, <command>systemd-run</command> will start the service asynchronously in the background and return after the
-    command has begun execution (unless <option>--no-block</option> or <option>--wait</option> are specified, see
-    below).</para>
+    command has begun execution (unless <option>--no-block</option>, <option>--wait</option>, <option>--pipe</option>,
+    or <option>--pty</option> are specified, see below).</para>
 
     <para>If a command is run as transient scope unit, it will be executed by <command>systemd-run</command>
     itself as parent process and will thus inherit the execution environment of the caller. However, the
@@ -176,11 +176,14 @@
         <term><option>--slice-inherit</option></term>
 
         <listitem><para>Make the new <filename>.service</filename> or <filename>.scope</filename> unit part
-        of the inherited slice. This option can be combined with <option>--slice=</option>.</para>
-
-        <para>An inherited slice is located within <command>systemd-run</command> slice. Example: if
-        <command>systemd-run</command> slice is <filename>foo.slice</filename>, and the
-        <option>--slice=</option> argument is <filename>bar</filename>, the unit will be placed under the
+        of the slice the <command>systemd-run</command> itself has been invoked in. This option may be
+        combined with <option>--slice=</option>, in which case the slice specified via
+        <option>--slice=</option> is placed within the slice the <command>systemd-run</command> command is
+        invoked in.</para>
+
+        <para>Example: consider <command>systemd-run</command> being invoked in the slice
+        <filename>foo.slice</filename>, and the <option>--slice=</option> argument is
+        <filename>bar</filename>. The unit will then be placed under
         <filename>foo-bar.slice</filename>.</para>
 
         <xi:include href="version-info.xml" xpointer="v246"/>
@@ -322,6 +325,11 @@
         to the terminal <command>systemd-run</command> is invoked on, via a pseudo TTY device. This allows running
         programs that expect interactive user input/output as services, such as interactive command shells.</para>
 
+        <para>This option will result in <command>systemd-run</command> synchronously waiting for
+        the transient service to terminate, similar to specifying <option>--wait</option>. If specified
+        along with <option>--wait</option>, <command>systemd-run</command> won't exit when manually disconnecting
+        from the pseudo TTY device.</para>
+
         <para>Note that
         <citerefentry><refentrytitle>machinectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>'s
         <command>shell</command> command is usually a better alternative for requesting a new, interactive login
@@ -338,21 +346,25 @@
 
         <listitem><para>If specified, standard input, output, and error of the transient service are inherited from the
         <command>systemd-run</command> command itself. This allows <command>systemd-run</command>
-        to be used within shell pipelines.
-        Note that this mode is not suitable for interactive command shells and similar, as the
-        service process will not become a TTY controller when invoked on a terminal. Use <option>--pty</option> instead
-        in that case.</para>
+        to be used within shell pipelines.</para>
+
+        <para>Note that this mode is not suitable for interactive command shells and similar, as the
+        service process will not become a TTY controller when invoked on a terminal. Use <option>--pty</option>
+        instead in that case.</para>
 
         <para>When both <option>--pipe</option> and <option>--pty</option> are used in combination the more appropriate
         option is automatically determined and used. Specifically, when invoked with standard input, output and error
         connected to a TTY <option>--pty</option> is used, and otherwise <option>--pipe</option>.</para>
 
+        <para>This option will result in <command>systemd-run</command> synchronously waiting for
+        the transient service to terminate, similar to specifying <option>--wait</option>.</para>
+
         <para>When this option is used the original file descriptors <command>systemd-run</command> receives are passed
         to the service processes as-is. If the service runs with different privileges than
-        <command>systemd-run</command>, this means the service might not be able to re-open the passed file
+        <command>systemd-run</command>, this means the service might not be able to reopen the passed file
         descriptors, due to normal file descriptor access restrictions. If the invoked process is a shell script that
         uses the <command>echo "hello" >/dev/stderr</command> construct for writing messages to stderr, this might
-        cause problems, as this only works if stderr can be re-opened. To mitigate this use the construct <command>echo
+        cause problems, as this only works if stderr can be reopened. To mitigate this use the construct <command>echo
         "hello" >&amp;2</command> instead, which is mostly equivalent and avoids this pitfall.</para>
 
         <xi:include href="version-info.xml" xpointer="v235"/></listitem>
@@ -485,10 +497,36 @@
         <xi:include href="version-info.xml" xpointer="v236"/></listitem>
       </varlistentry>
 
+      <varlistentry>
+        <term><option>--ignore-failure</option></term>
+
+        <listitem><para>By default, if the specified command fails the invoked unit will be marked failed
+        (though possibly still unloaded, see <option>--collect=</option>, above), and this is reported in the
+        logs. If this switch is specified this is suppressed and any non-success exit status/code of the
+        command is treated as success.</para>
+
+        <xi:include href="version-info.xml" xpointer="v256"/></listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><option>--background=<replaceable>COLOR</replaceable></option></term>
+
+        <listitem><para>Change the terminal background color to the specified ANSI color as long as the
+        session lasts. The color specified should be an ANSI X3.64 SGR background color, i.e. strings such as
+        <literal>40</literal>, <literal>41</literal>, …, <literal>47</literal>, <literal>48;2;…</literal>,
+        <literal>48;5;…</literal>. See <ulink
+        url="https://en.wikipedia.org/wiki/ANSI_escape_code#SGR_(Select_Graphic_Rendition)_parameters">ANSI
+        Escape Code (Wikipedia)</ulink> for details.</para>
+
+        <xi:include href="version-info.xml" xpointer="v256"/>
+        </listitem>
+      </varlistentry>
+
       <xi:include href="user-system-options.xml" xpointer="user" />
       <xi:include href="user-system-options.xml" xpointer="system" />
       <xi:include href="user-system-options.xml" xpointer="host" />
       <xi:include href="user-system-options.xml" xpointer="machine" />
+      <xi:include href="user-system-options.xml" xpointer="capsule" />
 
       <xi:include href="standard-options.xml" xpointer="help" />
       <xi:include href="standard-options.xml" xpointer="version" />
@@ -666,19 +704,20 @@ $ systemd-run --user --wait -p SuccessExitStatus=SIGUSR1 --expand-environment=no
 
   <refsect1>
     <title>See Also</title>
-    <para>
-      <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
-      <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
-      <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
-      <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
-      <citerefentry><refentrytitle>systemd.scope</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
-      <citerefentry><refentrytitle>systemd.slice</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
-      <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
-      <citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
-      <citerefentry><refentrytitle>systemd.timer</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
-      <citerefentry><refentrytitle>systemd-mount</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
-      <citerefentry><refentrytitle>machinectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>
-    </para>
+    <para><simplelist type="inline">
+      <member><citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
+      <member><citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
+      <member><citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry></member>
+      <member><citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry></member>
+      <member><citerefentry><refentrytitle>systemd.scope</refentrytitle><manvolnum>5</manvolnum></citerefentry></member>
+      <member><citerefentry><refentrytitle>systemd.slice</refentrytitle><manvolnum>5</manvolnum></citerefentry></member>
+      <member><citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry></member>
+      <member><citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry></member>
+      <member><citerefentry><refentrytitle>systemd.timer</refentrytitle><manvolnum>5</manvolnum></citerefentry></member>
+      <member><citerefentry><refentrytitle>systemd-mount</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
+      <member><citerefentry><refentrytitle>machinectl</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
+      <member><citerefentry><refentrytitle>run0</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
+    </simplelist></para>
   </refsect1>
 
 </refentry>