From 30d88d54f613f9f7831172876ebfd9e285fb043b Mon Sep 17 00:00:00 2001

From: =?UTF-8?q?Zbigniew=20J=C4=99drzejewski-Szmek?= <zbyszek@in.waw.pl>

Date: Tue, 7 Oct 2014 09:19:24 -0400

Subject: [PATCH] man: move commandline parsing to a separate section

It is very long already, and obscures the description of

ExecStart, and it is about to get longer.

---

 man/systemd.service.xml | 298 ++++++++++++++++++++++++------------------------

 1 file changed, 148 insertions(+), 150 deletions(-)

diff --git a/man/systemd.service.xml b/man/systemd.service.xml

index b9a2f8d82f..dbc82edbd4 100644

--- a/man/systemd.service.xml

+++ b/man/systemd.service.xml

@@ -352,72 +352,59 @@

                                 <term><varname>ExecStart=</varname></term>

                                 <listitem><para>Commands with their

                                 arguments that are executed when this

-                                service is started. For each of the

-                                specified commands, the first argument

-                                must be an absolute and literal path

-                                to an executable.</para>

+                                service is started. The value is split

+                                into zero or more command lines is

+                                according to the rules described below

+                                (see section "Command Lines" below).

+                                </para>

                                 <para>When <varname>Type</varname> is

                                 not <option>oneshot</option>, only one

                                 command may and must be given. When

                                 <varname>Type=oneshot</varname> is

-                                used, none or more than one command

-                                may be specified. Multiple command

-                                lines may be concatenated in a single

-                                directive by separating them with

-                                semicolons (these semicolons must be

-                                passed as separate

-                                words). Alternatively, this directive

-                                may be specified more than once with

-                                the same effect.  Lone semicolons may

-                                be escaped as

-                                <literal>\;</literal>. If the empty

-                                string is assigned to this option, the

-                                list of commands to start is reset,

-                                prior assignments of this option will

-                                have no effect. If no

+                                used, zero or more commands may be

+                                specified. This can be specified by

+                                providing multiple command lines in

+                                the same directive , or alternatively,

+                                this directive may be specified more

+                                than once with the same effect. If the

+                                empty string is assigned to this

+                                option, the list of commands to start

+                                is reset, prior assignments of this

+                                option will have no effect. If no

                                 <varname>ExecStart=</varname> is

                                 specified, then the service must have

                                 <varname>RemainAfterExit=yes</varname>

                                 set.</para>

-                                <para>Each command line is split on

-                                whitespace, with the first item being

-                                the command to execute, and the

-                                subsequent items being the arguments.

-                                Double quotes ("...") and single

-                                quotes ('...') may be used, in which

-                                case everything until the next

-                                matching quote becomes part of the

-                                same argument. Quotes themselves are

-                                removed after parsing. In addition, a

-                                trailing backslash

-                                (<literal>\</literal>) may be used to

-                                merge lines. This syntax is intended

-                                to be very similar to shell syntax,

-                                but only the meta-characters and

-                                expansions described in the following

-                                paragraphs are understood.

-                                Specifically, redirection using

-                                <literal><</literal>,

-                                <literal><<</literal>,

-                                <literal>></literal>, and

-                                <literal>>></literal>, pipes

-                                using <literal>|</literal>, and

-                                running programs in the background

-                                using <literal>&</literal>

-                                and <emphasis>other elements of shell

-                                syntax are not supported</emphasis>.

-                                </para>

+                                <para>For each of the specified

+                                commands, the first argument must be

+                                an absolute and literal path to an

+                                executable. Optionally, if the

+                                absolute file name is prefixed with

+                                <literal>@</literal>, the second token

+                                will be passed as

+                                <literal>argv[0]</literal> to the

+                                executed process, followed by the

+                                further arguments specified. If the

+                                absolute filename 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

+                                ignored and considered success. If

+                                both <literal>-</literal> and

+                                <literal>@</literal> are used, they

+                                can appear in either order.</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 <literal>-</literal>), other lines

-                                are not executed, and the unit is

-                                considered failed.</para>

+                                with <literal>-</literal>), other

+                                lines are not executed, and the unit

+                                is considered failed.</para>

                                 <para>Unless

                                 <varname>Type=forking</varname> is

@@ -425,106 +412,6 @@

                                 command line will be considered the

                                 main process of the daemon.</para>

-                                <para>The command line accepts

-                                <literal>%</literal> specifiers as

-                                described in

-                                <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>.

-                                Note that the first argument of the

-                                command line (i.e. the program to

-                                execute) may not include

-                                specifiers.</para>

-

-                                <para>Basic environment variable

-                                substitution is supported. Use

-                                <literal>${FOO}</literal> as part of a

-                                word, or as a word of its own, on the

-                                command line, in which case it will be

-                                replaced by the value of the

-                                environment variable including all

-                                whitespace it contains, resulting in a

-                                single argument. Use

-                                <literal>$FOO</literal> as a separate

-                                word on the command line, in which

-                                case it will be replaced by the value

-                                of the environment variable split at

-                                whitespace, resulting in zero or more

-                                arguments. To pass a literal dollar

-                                sign, use <literal>$$</literal>.

-                                Variables whose value is not known at

-                                expansion time are treated as empty

-                                strings. Note that the first argument

-                                (i.e. the program to execute) may not

-                                be a variable.</para>

-

-                                <para>Variables to be used in this

-                                fashion may be defined through

-                                <varname>Environment=</varname> and

-                                <varname>EnvironmentFile=</varname>.

-                                In addition, variables listed in the

-                                section "Environment variables in

-                                spawned processes" in

-                                <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>,

-                                which are considered "static

-                                configuration", may be used (this includes

-                                e.g. <varname>$USER</varname>, but not

-                                <varname>$TERM</varname>).</para>

-

-                                <para>Optionally, if the absolute file

-                                name is prefixed with

-                                <literal>@</literal>, the second token

-                                will be passed as

-                                <literal>argv[0]</literal> to the

-                                executed process, followed by the

-                                further arguments specified. If the

-                                absolute filename 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 ignored

-                                and considered success. If both

-                                <literal>-</literal> and

-                                <literal>@</literal> are used, they

-                                can appear in either order.</para>

-

-                                <para>Note that this setting does not

-                                directly support shell command

-                                lines. If shell command lines are to

-                                be used, they need to be passed

-                                explicitly to a shell implementation

-                                of some kind. Example:</para>

-                                <programlisting>ExecStart=/bin/sh -c 'dmesg | tac'</programlisting>

-                                <para>Example:</para>

-                                <programlisting>ExecStart=/bin/echo one ; /bin/echo "two two"</programlisting>

-                                <para>This will execute

-                                <command>/bin/echo</command> two

-                                times, each time with one argument:

-                                <literal>one</literal> and

-                                <literal>two two</literal>,

-                                respectively. Because two commands are

-                                specified,

-                                <varname>Type=oneshot</varname> must

-                                be used.</para>

-

-                                <para>Example:</para>

-                                <programlisting>ExecStart=/bin/echo / >/dev/null & \; \

-/bin/ls</programlisting>

-                                <para>This will execute

-                                <command>/bin/echo</command> with five

-                                arguments: <literal>/</literal>,

-                                <literal>>/dev/null</literal>,

-                                <literal>&</literal>,

-                                <literal>;</literal>, and

-                                <literal>/bin/ls</literal>.</para>

-

-                                <para>Example:</para>

-                                <programlisting>Environment="ONE=one" 'TWO=two two'

-ExecStart=/bin/echo $ONE $TWO ${TWO}</programlisting>

-                                <para>This will execute

-                                <command>/bin/echo</command> with four

-                                arguments: <literal>one</literal>,

-                                <literal>two</literal>,

-                                <literal>two</literal>, and

-                                <literal>two two</literal>.</para>

                               </listitem>

                         </varlistentry>

@@ -1274,6 +1161,117 @@ ExecStart=/bin/echo $ONE $TWO ${TWO}</programlisting>

         </refsect1>

         <refsect1>

+                <title>Command lines</title>

+

+                <para>This section describes command line parsing and

+                variable and specifier substitions for

+                <varname>ExecStart=</varname>,

+                <varname>ExecStartPre=</varname>,

+                <varname>ExecStartPost=</varname>,

+                <varname>ExecReload=</varname>,

+                <varname>ExecStop=</varname>, and

+                <varname>ExecStopPost=</varname> options.</para>

+

+                <para>Multiple command lines may be concatenated in a

+                single directive by separating them with semicolons

+                (these semicolons must be passed as separate words).

+                Lone semicolons may be escaped as

+                <literal>\;</literal>.</para>

+

+                <para>Each command line is split on whitespace, with

+                the first item being the command to execute, and the

+                subsequent items being the arguments.  Double quotes

+                ("...") and single quotes ('...') may be used, in

+                which case everything until the next matching quote

+                becomes part of the same argument. Quotes themselves

+                are removed after parsing. In addition, a trailing

+                backslash (<literal>\</literal>) may be used to merge

+                lines. </para>

+

+                <para>This syntax is intended to be very similar to

+                shell syntax, but only the meta-characters and

+                expansions described in the following paragraphs are

+                understood.  Specifically, redirection using

+                <literal><</literal>, <literal><<</literal>,

+                <literal>></literal>, and

+                <literal>>></literal>, pipes using

+                <literal>|</literal>, running programs in the

+                background using <literal>&</literal>, and

+                <emphasis>other elements of shell syntax are not

+                supported</emphasis>.</para>

+

+                <para>The command line accepts <literal>%</literal>

+                specifiers as described in

+                <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>.

+                Note that the first argument of the command line

+                (i.e. the program to execute) may not include

+                specifiers.</para>

+

+                <para>Basic environment variable substitution is

+                supported. Use <literal>${FOO}</literal> as part of a

+                word, or as a word of its own, on the command line, in

+                which case it will be replaced by the value of the

+                environment variable including all whitespace it

+                contains, resulting in a single argument. Use

+                <literal>$FOO</literal> as a separate word on the

+                command line, in which case it will be replaced by the

+                value of the environment variable split at whitespace,

+                resulting in zero or more arguments. To pass a literal

+                dollar sign, use <literal>$$</literal>.  Variables

+                whose value is not known at expansion time are treated

+                as empty strings. Note that the first argument

+                (i.e. the program to execute) may not be a

+                variable.</para>

+

+                <para>Variables to be used in this fashion may be

+                defined through <varname>Environment=</varname> and

+                <varname>EnvironmentFile=</varname>.  In addition,

+                variables listed in the section "Environment variables

+                in spawned processes" in

+                <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>,

+                which are considered "static configuration", may be

+                used (this includes e.g. <varname>$USER</varname>, but

+                not <varname>$TERM</varname>).</para>

+

+                <para>Note that shell command lines are not directly

+                supported. If shell command lines are to be used, they

+                need to be passed explicitly to a shell implementation

+                of some kind. Example:</para>

+                <programlisting>ExecStart=/bin/sh -c 'dmesg | tac'</programlisting>

+

+                <para>Example:</para>

+

+                <programlisting>ExecStart=/bin/echo one ; /bin/echo "two two"</programlisting>

+

+                <para>This will execute <command>/bin/echo</command>

+                two times, each time with one argument:

+                <literal>one</literal> and <literal>two two</literal>,

+                respectively. Because two commands are specified,

+                <varname>Type=oneshot</varname> must be used.</para>

+

+                <para>Example:</para>

+

+                <programlisting>ExecStart=/bin/echo / >/dev/null & \; \

+/bin/ls</programlisting>

+

+                <para>This will execute <command>/bin/echo</command>

+                with five arguments: <literal>/</literal>,

+                <literal>>/dev/null</literal>,

+                <literal>&</literal>, <literal>;</literal>, and

+                <literal>/bin/ls</literal>.</para>

+

+                <para>Example:</para>

+

+                <programlisting>Environment="ONE=one" 'TWO=two two'

+ExecStart=/bin/echo $ONE $TWO ${TWO}</programlisting>

+

+                <para>This will execute <command>/bin/echo</command>

+                with four arguments: <literal>one</literal>,

+                <literal>two</literal>, <literal>two</literal>, and

+                <literal>two two</literal>.</para>

+        </refsect1>

+

+        <refsect1>

                   <title>See Also</title>

                   <para>

                           <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,