Merge pull request #27128 from keszybz/sd-bus-docs-and-error-messages

Improvements to man pages for systemd.service, sd-bus, and better error messages

4 files changed, 140 insertions, 108 deletions

diff --git a/man/rules/meson.build b/man/rules/meson.build
index 39cc55a929..63a68c3211 100644
--- a/man/rules/meson.build
+++ b/man/rules/meson.build
@@ -85,6 +85,7 @@ manpages = [
    'SD_BUS_ERROR_INCONSISTENT_MESSAGE',
    'SD_BUS_ERROR_INTERACTIVE_AUTHORIZATION_REQUIRED',
    'SD_BUS_ERROR_INVALID_ARGS',
+   'SD_BUS_ERROR_INVALID_FILE_CONTENT',
    'SD_BUS_ERROR_INVALID_SIGNATURE',
    'SD_BUS_ERROR_IO_ERROR',
    'SD_BUS_ERROR_LIMITS_EXCEEDED',
@@ -96,8 +97,11 @@ manpages = [
    'SD_BUS_ERROR_NO_NETWORK',
    'SD_BUS_ERROR_NO_REPLY',
    'SD_BUS_ERROR_NO_SERVER',
+   'SD_BUS_ERROR_OBJECT_PATH_IN_USE',
    'SD_BUS_ERROR_PROPERTY_READ_ONLY',
+   'SD_BUS_ERROR_SELINUX_SECURITY_CONTEXT_UNKNOWN',
    'SD_BUS_ERROR_SERVICE_UNKNOWN',
+   'SD_BUS_ERROR_TIMED_OUT',
    'SD_BUS_ERROR_TIMEOUT',
    'SD_BUS_ERROR_UNIX_PROCESS_ID_UNKNOWN',
    'SD_BUS_ERROR_UNKNOWN_INTERFACE',
diff --git a/man/sd-bus-errors.xml b/man/sd-bus-errors.xml
index f3b1515c78..dc9d9fc63b 100644
--- a/man/sd-bus-errors.xml
+++ b/man/sd-bus-errors.xml
@@ -45,9 +45,13 @@
     <refname>SD_BUS_ERROR_UNIX_PROCESS_ID_UNKNOWN</refname>
     <refname>SD_BUS_ERROR_INVALID_SIGNATURE</refname>
     <refname>SD_BUS_ERROR_INCONSISTENT_MESSAGE</refname>
+    <refname>SD_BUS_ERROR_TIMED_OUT</refname>
     <refname>SD_BUS_ERROR_MATCH_RULE_NOT_FOUND</refname>
     <refname>SD_BUS_ERROR_MATCH_RULE_INVALID</refname>
     <refname>SD_BUS_ERROR_INTERACTIVE_AUTHORIZATION_REQUIRED</refname>
+    <refname>SD_BUS_ERROR_INVALID_FILE_CONTENT</refname>
+    <refname>SD_BUS_ERROR_SELINUX_SECURITY_CONTEXT_UNKNOWN</refname>
+    <refname>SD_BUS_ERROR_OBJECT_PATH_IN_USE</refname>
 
     <refpurpose>Standard D-Bus error names</refpurpose>
   </refnamediv>
@@ -56,38 +60,44 @@
     <funcsynopsis>
       <funcsynopsisinfo>#include &lt;systemd/sd-bus.h&gt;</funcsynopsisinfo>
 
-<funcsynopsisinfo>#define SD_BUS_ERROR_FAILED                     "org.freedesktop.DBus.Error.Failed"
-#define SD_BUS_ERROR_NO_MEMORY                  "org.freedesktop.DBus.Error.NoMemory"
-#define SD_BUS_ERROR_SERVICE_UNKNOWN            "org.freedesktop.DBus.Error.ServiceUnknown"
-#define SD_BUS_ERROR_NAME_HAS_NO_OWNER          "org.freedesktop.DBus.Error.NameHasNoOwner"
-#define SD_BUS_ERROR_NO_REPLY                   "org.freedesktop.DBus.Error.NoReply"
-#define SD_BUS_ERROR_IO_ERROR                   "org.freedesktop.DBus.Error.IOError"
-#define SD_BUS_ERROR_BAD_ADDRESS                "org.freedesktop.DBus.Error.BadAddress"
-#define SD_BUS_ERROR_NOT_SUPPORTED              "org.freedesktop.DBus.Error.NotSupported"
-#define SD_BUS_ERROR_LIMITS_EXCEEDED            "org.freedesktop.DBus.Error.LimitsExceeded"
-#define SD_BUS_ERROR_ACCESS_DENIED              "org.freedesktop.DBus.Error.AccessDenied"
-#define SD_BUS_ERROR_AUTH_FAILED                "org.freedesktop.DBus.Error.AuthFailed"
-#define SD_BUS_ERROR_NO_SERVER                  "org.freedesktop.DBus.Error.NoServer"
-#define SD_BUS_ERROR_TIMEOUT                    "org.freedesktop.DBus.Error.Timeout"
-#define SD_BUS_ERROR_NO_NETWORK                 "org.freedesktop.DBus.Error.NoNetwork"
-#define SD_BUS_ERROR_ADDRESS_IN_USE             "org.freedesktop.DBus.Error.AddressInUse"
-#define SD_BUS_ERROR_DISCONNECTED               "org.freedesktop.DBus.Error.Disconnected"
-#define SD_BUS_ERROR_INVALID_ARGS               "org.freedesktop.DBus.Error.InvalidArgs"
-#define SD_BUS_ERROR_FILE_NOT_FOUND             "org.freedesktop.DBus.Error.FileNotFound"
-#define SD_BUS_ERROR_FILE_EXISTS                "org.freedesktop.DBus.Error.FileExists"
-#define SD_BUS_ERROR_UNKNOWN_METHOD             "org.freedesktop.DBus.Error.UnknownMethod"
-#define SD_BUS_ERROR_UNKNOWN_OBJECT             "org.freedesktop.DBus.Error.UnknownObject"
-#define SD_BUS_ERROR_UNKNOWN_INTERFACE          "org.freedesktop.DBus.Error.UnknownInterface"
-#define SD_BUS_ERROR_UNKNOWN_PROPERTY           "org.freedesktop.DBus.Error.UnknownProperty"
-#define SD_BUS_ERROR_PROPERTY_READ_ONLY         "org.freedesktop.DBus.Error.PropertyReadOnly"
-#define SD_BUS_ERROR_UNIX_PROCESS_ID_UNKNOWN    "org.freedesktop.DBus.Error.UnixProcessIdUnknown"
-#define SD_BUS_ERROR_INVALID_SIGNATURE          "org.freedesktop.DBus.Error.InvalidSignature"
-#define SD_BUS_ERROR_INCONSISTENT_MESSAGE       "org.freedesktop.DBus.Error.InconsistentMessage"
-#define SD_BUS_ERROR_MATCH_RULE_NOT_FOUND       "org.freedesktop.DBus.Error.MatchRuleNotFound"
-#define SD_BUS_ERROR_MATCH_RULE_INVALID         "org.freedesktop.DBus.Error.MatchRuleInvalid"
+      <funcsynopsisinfo>
+#define SD_BUS_ERROR_FAILED                  "org.freedesktop.DBus.Error.Failed"
+#define SD_BUS_ERROR_NO_MEMORY               "org.freedesktop.DBus.Error.NoMemory"
+#define SD_BUS_ERROR_SERVICE_UNKNOWN         "org.freedesktop.DBus.Error.ServiceUnknown"
+#define SD_BUS_ERROR_NAME_HAS_NO_OWNER       "org.freedesktop.DBus.Error.NameHasNoOwner"
+#define SD_BUS_ERROR_NO_REPLY                "org.freedesktop.DBus.Error.NoReply"
+#define SD_BUS_ERROR_IO_ERROR                "org.freedesktop.DBus.Error.IOError"
+#define SD_BUS_ERROR_BAD_ADDRESS             "org.freedesktop.DBus.Error.BadAddress"
+#define SD_BUS_ERROR_NOT_SUPPORTED           "org.freedesktop.DBus.Error.NotSupported"
+#define SD_BUS_ERROR_LIMITS_EXCEEDED         "org.freedesktop.DBus.Error.LimitsExceeded"
+#define SD_BUS_ERROR_ACCESS_DENIED           "org.freedesktop.DBus.Error.AccessDenied"
+#define SD_BUS_ERROR_AUTH_FAILED             "org.freedesktop.DBus.Error.AuthFailed"
+#define SD_BUS_ERROR_NO_SERVER               "org.freedesktop.DBus.Error.NoServer"
+#define SD_BUS_ERROR_TIMEOUT                 "org.freedesktop.DBus.Error.Timeout"
+#define SD_BUS_ERROR_NO_NETWORK              "org.freedesktop.DBus.Error.NoNetwork"
+#define SD_BUS_ERROR_ADDRESS_IN_USE          "org.freedesktop.DBus.Error.AddressInUse"
+#define SD_BUS_ERROR_DISCONNECTED            "org.freedesktop.DBus.Error.Disconnected"
+#define SD_BUS_ERROR_INVALID_ARGS            "org.freedesktop.DBus.Error.InvalidArgs"
+#define SD_BUS_ERROR_FILE_NOT_FOUND          "org.freedesktop.DBus.Error.FileNotFound"
+#define SD_BUS_ERROR_FILE_EXISTS             "org.freedesktop.DBus.Error.FileExists"
+#define SD_BUS_ERROR_UNKNOWN_METHOD          "org.freedesktop.DBus.Error.UnknownMethod"
+#define SD_BUS_ERROR_UNKNOWN_OBJECT          "org.freedesktop.DBus.Error.UnknownObject"
+#define SD_BUS_ERROR_UNKNOWN_INTERFACE       "org.freedesktop.DBus.Error.UnknownInterface"
+#define SD_BUS_ERROR_UNKNOWN_PROPERTY        "org.freedesktop.DBus.Error.UnknownProperty"
+#define SD_BUS_ERROR_PROPERTY_READ_ONLY      "org.freedesktop.DBus.Error.PropertyReadOnly"
+#define SD_BUS_ERROR_UNIX_PROCESS_ID_UNKNOWN "org.freedesktop.DBus.Error.UnixProcessIdUnknown"
+#define SD_BUS_ERROR_INVALID_SIGNATURE       "org.freedesktop.DBus.Error.InvalidSignature"
+#define SD_BUS_ERROR_INCONSISTENT_MESSAGE    "org.freedesktop.DBus.Error.InconsistentMessage"
+#define SD_BUS_ERROR_TIMED_OUT               "org.freedesktop.DBus.Error.TimedOut"
+#define SD_BUS_ERROR_MATCH_RULE_NOT_FOUND    "org.freedesktop.DBus.Error.MatchRuleNotFound"
+#define SD_BUS_ERROR_MATCH_RULE_INVALID      "org.freedesktop.DBus.Error.MatchRuleInvalid"
 #define SD_BUS_ERROR_INTERACTIVE_AUTHORIZATION_REQUIRED \
-                                                "org.freedesktop.DBus.Error.InteractiveAuthorizationRequired"</funcsynopsisinfo>
-
+                                             "org.freedesktop.DBus.Error.InteractiveAuthorizationRequired"
+#define SD_BUS_ERROR_INVALID_FILE_CONTENT    "org.freedesktop.DBus.Error.InvalidFileContent"
+#define SD_BUS_ERROR_SELINUX_SECURITY_CONTEXT_UNKNOWN \
+                                             "org.freedesktop.DBus.Error.SELinuxSecurityContextUnknown"
+#define SD_BUS_ERROR_OBJECT_PATH_IN_USE      "org.freedesktop.DBus.Error.ObjectPathInUse"
+      </funcsynopsisinfo>
     </funcsynopsis>
   </refsynopsisdiv>
 
diff --git a/man/sd_bus_message_open_container.xml b/man/sd_bus_message_open_container.xml
index 688f43227b..0b9164e9bf 100644
--- a/man/sd_bus_message_open_container.xml
+++ b/man/sd_bus_message_open_container.xml
@@ -91,7 +91,7 @@
     with <function>sd_bus_message_enter_container()</function>. It behaves mostly the same as
     <function>sd_bus_message_close_container()</function>. Note that
     <function>sd_bus_message_exit_container()</function> may only be called after iterating through all
-    members of the container, i.e. reading or skipping them. Use
+    members of the container, i.e. reading or skipping over them. Use
     <citerefentry><refentrytitle>sd_bus_message_skip</refentrytitle><manvolnum>3</manvolnum></citerefentry>
     to skip over fields of a container in order to be able to exit the container with
     <function>sd_bus_message_exit_container()</function> without reading all members.</para>
@@ -122,6 +122,20 @@
         </varlistentry>
 
         <varlistentry>
+          <term><constant>-EBADMSG</constant></term>
+
+          <listitem><para>Message <parameter>m</parameter> has invalid structure.</para></listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term><constant>-ENXIO</constant></term>
+
+          <listitem><para>Message <parameter>m</parameter> does not have a container of type
+          <parameter>type</parameter> at the current position, or the contents do not match
+          <parameter>contents</parameter>.</para></listitem>
+        </varlistentry>
+
+        <varlistentry>
           <term><constant>-EPERM</constant></term>
 
           <listitem><para>The message <parameter>m</parameter> is already sealed.</para></listitem>
diff --git a/man/systemd.service.xml b/man/systemd.service.xml
index 665128ee77..f64a8e538f 100644
--- a/man/systemd.service.xml
+++ b/man/systemd.service.xml
@@ -356,11 +356,8 @@
 
       <varlistentry>
         <term><varname>ExecStart=</varname></term>
-        <listitem><para>Commands with their arguments that are
-        executed when this service is started. The value is split into
-        zero or more command lines according to the rules described
-        below (see section "Command Lines" below).
-        </para>
+        <listitem><para>Commands that are executed when this service is started. The value is split into zero
+        or more command lines according to the rules described in the section "Command Lines" below.</para>
 
         <para>Unless <varname>Type=</varname> is <option>oneshot</option>, exactly one command must be given. When
         <varname>Type=oneshot</varname> is used, zero or more commands may be specified. Commands may be specified by
@@ -371,66 +368,6 @@
         <varname>ExecStop=</varname> line set. (Services lacking both <varname>ExecStart=</varname> and
         <varname>ExecStop=</varname> are not valid.)</para>
 
-        <para>For each of the specified commands, the first argument must be either an absolute path to an executable
-        or a simple file name without any slashes. Optionally, this filename may be prefixed with a number of special
-        characters:</para>
-
-        <table>
-          <title>Special executable prefixes</title>
-
-          <tgroup cols='2'>
-            <colspec colname='prefix'/>
-            <colspec colname='meaning'/>
-
-            <thead>
-              <row>
-                <entry>Prefix</entry>
-                <entry>Effect</entry>
-              </row>
-            </thead>
-            <tbody>
-              <row>
-                <entry><literal>@</literal></entry>
-                <entry>If the executable path is prefixed with <literal>@</literal>, the second specified token will be passed as <literal>argv[0]</literal> to the executed process (instead of the actual filename), followed by the further arguments specified.</entry>
-              </row>
-
-              <row>
-                <entry><literal>-</literal></entry>
-                <entry>If the executable path is prefixed with <literal>-</literal>, an exit code of the command normally considered a failure (i.e. non-zero exit status or abnormal exit due to signal) is recorded, but has no further effect and is considered equivalent to success.</entry>
-              </row>
-
-              <row>
-                <entry><literal>:</literal></entry>
-                <entry>If the executable path is prefixed with <literal>:</literal>, environment variable substitution (as described by the "Command Lines" section below) is not applied.</entry>
-              </row>
-
-              <row>
-                <entry><literal>+</literal></entry>
-                <entry>If the executable path is prefixed with <literal>+</literal> then the process is executed with full privileges. In this mode privilege restrictions configured with <varname>User=</varname>, <varname>Group=</varname>, <varname>CapabilityBoundingSet=</varname> or the various file system namespacing options (such as <varname>PrivateDevices=</varname>, <varname>PrivateTmp=</varname>) are not applied to the invoked command line (but still affect any other <varname>ExecStart=</varname>, <varname>ExecStop=</varname>, … lines). However, note that this will not bypass options that apply to the whole control group, such as <varname>DevicePolicy=</varname>, see <citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry> for the full list.</entry>
-              </row>
-
-              <row>
-                <entry><literal>!</literal></entry>
-
-                <entry>Similar to the <literal>+</literal> character discussed above this permits invoking command lines with elevated privileges. However, unlike <literal>+</literal> the <literal>!</literal> character exclusively alters the effect of <varname>User=</varname>, <varname>Group=</varname> and <varname>SupplementaryGroups=</varname>, i.e. only the stanzas that affect user and group credentials. Note that this setting may be combined with <varname>DynamicUser=</varname>, in which case a dynamic user/group pair is allocated before the command is invoked, but credential changing is left to the executed process itself.</entry>
-              </row>
-
-              <row>
-                <entry><literal>!!</literal></entry>
-
-                <entry>This prefix is very similar to <literal>!</literal>, however it only has an effect on systems lacking support for ambient process capabilities, i.e. without support for <varname>AmbientCapabilities=</varname>. It's intended to be used for unit files that take benefit of ambient capabilities to run processes with minimal privileges wherever possible while remaining compatible with systems that lack ambient capabilities support. Note that when <literal>!!</literal> is used, and a system lacking ambient capability support is detected any configured <varname>SystemCallFilter=</varname> and <varname>CapabilityBoundingSet=</varname> stanzas are implicitly modified, in order to permit spawned processes to drop credentials and capabilities themselves, even if this is configured to not be allowed. Moreover, if this prefix is used and a system lacking ambient capability support is detected <varname>AmbientCapabilities=</varname> will be skipped and not be applied. On systems supporting ambient capabilities, <literal>!!</literal> has no effect and is redundant.</entry>
-              </row>
-            </tbody>
-          </tgroup>
-        </table>
-
-        <para><literal>@</literal>, <literal>-</literal>, <literal>:</literal>, and one of
-        <literal>+</literal>/<literal>!</literal>/<literal>!!</literal> may be used together and they can appear in any
-        order. However, only one of <literal>+</literal>, <literal>!</literal>, <literal>!!</literal> may be used at a
-        time. Note that these prefixes are also supported for the other command line settings,
-        i.e. <varname>ExecStartPre=</varname>, <varname>ExecStartPost=</varname>, <varname>ExecReload=</varname>,
-        <varname>ExecStop=</varname> and <varname>ExecStopPost=</varname>.</para>
-
         <para>If more than one command is specified, the commands are
         invoked sequentially in the order they appear in the unit
         file. If one of the commands fails (and is not prefixed with
@@ -1294,6 +1231,73 @@
 
     <para>The command to execute may contain spaces, but control characters are not allowed.</para>
 
+    <para>Each command may be prefixed with a number of special characters:</para>
+
+    <table>
+      <title>Special executable prefixes</title>
+
+      <tgroup cols='2'>
+        <colspec colname='prefix'/>
+        <colspec colname='meaning'/>
+
+        <thead>
+          <row>
+            <entry>Prefix</entry>
+            <entry>Effect</entry>
+          </row>
+        </thead>
+        <tbody>
+          <row>
+            <entry><literal>@</literal></entry>
+            <entry>If the executable path is prefixed with <literal>@</literal>, the second specified token will be passed as <constant>argv[0]</constant> to the executed process (instead of the actual filename), followed by the further arguments specified.</entry>
+          </row>
+
+          <row>
+            <entry><literal>-</literal></entry>
+            <entry>If the executable path is prefixed with <literal>-</literal>, an exit code of the command normally considered a failure (i.e. non-zero exit status or abnormal exit due to signal) is recorded, but has no further effect and is considered equivalent to success.</entry>
+          </row>
+
+          <row>
+            <entry><literal>:</literal></entry>
+            <entry>If the executable path is prefixed with <literal>:</literal>, environment variable substitution (as described by the "Command Lines" section below) is not applied.</entry>
+          </row>
+
+          <row>
+            <entry><literal>+</literal></entry>
+            <entry>If the executable path is prefixed with <literal>+</literal> then the process is executed with full privileges. In this mode privilege restrictions configured with <varname>User=</varname>, <varname>Group=</varname>, <varname>CapabilityBoundingSet=</varname> or the various file system namespacing options (such as <varname>PrivateDevices=</varname>, <varname>PrivateTmp=</varname>) are not applied to the invoked command line (but still affect any other <varname>ExecStart=</varname>, <varname>ExecStop=</varname>, … lines). However, note that this will not bypass options that apply to the whole control group, such as <varname>DevicePolicy=</varname>, see <citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry> for the full list.</entry>
+          </row>
+
+          <row>
+            <entry><literal>!</literal></entry>
+
+            <entry>Similar to the <literal>+</literal> character discussed above this permits invoking command lines with elevated privileges. However, unlike <literal>+</literal> the <literal>!</literal> character exclusively alters the effect of <varname>User=</varname>, <varname>Group=</varname> and <varname>SupplementaryGroups=</varname>, i.e. only the stanzas that affect user and group credentials. Note that this setting may be combined with <varname>DynamicUser=</varname>, in which case a dynamic user/group pair is allocated before the command is invoked, but credential changing is left to the executed process itself.</entry>
+          </row>
+
+          <row>
+            <entry><literal>!!</literal></entry>
+
+            <entry>This prefix is very similar to <literal>!</literal>, however it only has an effect on systems lacking support for ambient process capabilities, i.e. without support for <varname>AmbientCapabilities=</varname>. It's intended to be used for unit files that take benefit of ambient capabilities to run processes with minimal privileges wherever possible while remaining compatible with systems that lack ambient capabilities support. Note that when <literal>!!</literal> is used, and a system lacking ambient capability support is detected any configured <varname>SystemCallFilter=</varname> and <varname>CapabilityBoundingSet=</varname> stanzas are implicitly modified, in order to permit spawned processes to drop credentials and capabilities themselves, even if this is configured to not be allowed. Moreover, if this prefix is used and a system lacking ambient capability support is detected <varname>AmbientCapabilities=</varname> will be skipped and not be applied. On systems supporting ambient capabilities, <literal>!!</literal> has no effect and is redundant.</entry>
+          </row>
+        </tbody>
+      </tgroup>
+    </table>
+
+    <para><literal>@</literal>, <literal>-</literal>, <literal>:</literal>, and one of
+    <literal>+</literal>/<literal>!</literal>/<literal>!!</literal> may be used together and they can appear in any
+    order. However, only one of <literal>+</literal>, <literal>!</literal>, <literal>!!</literal> may be used at a
+    time.</para>
+
+    <para>For each command, the first argument must be either an absolute path to an executable or a simple
+    file name without any slashes. If the command is not a full (absolute) path, it will be resolved to a
+    full path using a fixed search path determined at compilation time. Searched directories include
+    <filename>/usr/local/bin/</filename>, <filename>/usr/bin/</filename>, <filename>/bin/</filename> on
+    systems using split <filename>/usr/bin/</filename> and <filename>/bin/</filename> directories, and their
+    <filename>sbin/</filename> counterparts on systems using split <filename>bin/</filename> and
+    <filename>sbin/</filename>. It is thus safe to use just the executable name in case of executables
+    located in any of the "standard" directories, and an absolute path must be used in other cases. Using an
+    absolute path is recommended to avoid ambiguity. Hint: this search path may be queried using
+    <command>systemd-path search-binaries-default</command>.</para>
+
     <para>The command line accepts <literal>%</literal> specifiers as described in
     <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para>
 
@@ -1308,17 +1312,6 @@
     For this type of expansion, quotes are respected when splitting
     into words, and afterwards removed.</para>
 
-    <para>If the command is not a full (absolute) path, it will be resolved to a full path using a
-    fixed search path determined at compilation time. Searched directories include
-    <filename>/usr/local/bin/</filename>, <filename>/usr/bin/</filename>, <filename>/bin/</filename>
-    on systems using split <filename>/usr/bin/</filename> and <filename>/bin/</filename>
-    directories, and their <filename>sbin/</filename> counterparts on systems using split
-    <filename>bin/</filename> and <filename>sbin/</filename>. It is thus safe to use just the
-    executable name in case of executables located in any of the "standard" directories, and an
-    absolute path must be used in other cases. Using an absolute path is recommended to avoid
-    ambiguity. Hint: this search path may be queried using
-    <command>systemd-path search-binaries-default</command>.</para>
-
     <para>Example:</para>
 
     <programlisting>Environment="ONE=one" 'TWO=two two'
@@ -1371,6 +1364,17 @@ ExecStart=/bin/echo $ONE $TWO $THREE</programlisting>
 
     <para>Example:</para>
 
+    <programlisting>Type=oneshot
+ExecStart=:echo $USER ; -false ; +:@true $TEST</programlisting>
+
+    <para>This will execute <command>/usr/bin/echo</command> with the literal argument
+    <literal>$USER</literal> (<literal>:</literal> suppresses variable expansion), and then
+    <command>/usr/bin/false</command> (the return value will be ignored because <literal>-</literal>
+    suppresses checking of the return value), and <command>/usr/bin/true</command> (with elevated privileges,
+    with <literal>$TEST</literal> as <constant>argv[0]</constant>).</para>
+
+    <para>Example:</para>
+
     <programlisting>ExecStart=echo / &gt;/dev/null &amp; \; \
 ls</programlisting>