man: always place <programlisting> and </programlisting> in a line with actual source...

[elogind.git] / man / systemd.service.xml

diff --git a/man/systemd.service.xml b/man/systemd.service.xml
index 103c495fbed5dacc3bbbc338d0cd4a52b380a4d4..6e9b6696fc533db90ac90c79f2f44e95b2c01abc 100644 (file)
--- a/man/systemd.service.xml
+++ b/man/systemd.service.xml
@@ -139,9 +139,11 @@
 
                                 <para>If set to
                                 <option>simple</option> (the default
 
                                 <para>If set to
                                 <option>simple</option> (the default

-                                value if <varname>BusName=</varname>
-                                is not specified), it is expected that
-                                the process configured with
+                                value if neither
+                                <varname>Type=</varname> nor
+                                <varname>BusName=</varname> are
+                                specified), it is expected that the
+                                process configured with

                                 <varname>ExecStart=</varname> is the
                                 main process of the service. In this
                                 mode, if the process offers
                                 <varname>ExecStart=</varname> is the
                                 main process of the service. In this
                                 mode, if the process offers


@@ -321,11 +323,7 @@
                                 (these semicolons must be passed as
                                 separate words). Alternatively, this
                                 directive may be specified more than
                                 (these semicolons must be passed as
                                 separate words). Alternatively, this
                                 directive may be specified more than

-                                once with the same effect. However,
-                                the latter syntax is not recommended
-                                for compatibility with parsers
-                                suitable for XDG
-                                <filename>.desktop</filename> files.
+                                once with the same effect.

                                 Lone semicolons may be escaped as
                                 <literal>\;</literal>. If the empty
                                 string is assigned to this option, the
                                 Lone semicolons may be escaped as
                                 <literal>\;</literal>. If the empty
                                 string is assigned to this option, the


@@ -394,16 +392,32 @@
                                 replaced by the value of the
                                 environment variable including all
                                 whitespace it contains, resulting in a
                                 replaced by the value of the
                                 environment variable including all
                                 whitespace it contains, resulting in a

-                                single argument.  Use
+                                single argument. Use

                                 <literal>$FOO</literal> as a separate
                                 word on the command line, in which
                                 case it will be replaced by the value
                                 <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 up
-                                at whitespace, resulting in zero or
-                                more arguments. To pass a literal dollar sign,
-                                use <literal>$$</literal>. Note that the first
-                                argument (i.e. the program to execute)
-                                may not be a variable.</para>
+                                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
+                                section "Environment variables in
+                                spawned processes" in
+                                <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>
+                                which are considered "static
+                                configuration" may used (this includes
+                                e.g. <varname>$USER</varname>, but not
+                                <varname>$TERM</varname>).</para>

 
                                 <para>Optionally, if the absolute file
                                 name is prefixed with
 
                                 <para>Optionally, if the absolute file
                                 name is prefixed with


@@ -428,31 +442,22 @@
                                 be used, they need to be passed
                                 explicitly to a shell implementation
                                 of some kind. Example:</para>
                                 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>Only select environment variables
-                                are set for executed commands. See
-                                <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
-                                </para>
-
+                                <programlisting>ExecStart=/bin/sh -c 'dmesg | tac'</programlisting>

                                 <para>Example:</para>
                                 <para>Example:</para>

-                                <programlisting>ExecStart=/bin/echo one ; /bin/echo "two two"
-                                </programlisting>
+                                <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. Since two commands are
                                 <para>This will execute
                                 <command>/bin/echo</command> two
                                 times, each time with one argument,
                                 <literal>one</literal> and
                                 <literal>two two</literal>,
                                 respectively. Since two commands are

-                                specified
+                                specified,

                                 <varname>Type=oneshot</varname> must
                                 be used.</para>
 
                                 <para>Example:</para>
                                 <programlisting>ExecStart=/bin/echo / &gt;/dev/null &amp; \; \
                                 <varname>Type=oneshot</varname> must
                                 be used.</para>
 
                                 <para>Example:</para>
                                 <programlisting>ExecStart=/bin/echo / &gt;/dev/null &amp; \; \

-/bin/ls
-                                </programlisting>
+/bin/ls</programlisting>

                                 <para>This will execute
                                 <command>/bin/echo</command> with five
                                 arguments: <literal>/</literal>,
                                 <para>This will execute
                                 <command>/bin/echo</command> with five
                                 arguments: <literal>/</literal>,


@@ -463,8 +468,7 @@
 
                                 <para>Example:</para>
                                 <programlisting>Environment="ONE=one" 'TWO=two two'
 
                                 <para>Example:</para>
                                 <programlisting>Environment="ONE=one" 'TWO=two two'

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

                                 <para>This will execute
                                 <command>/bin/echo</command> with four
                                 arguments: <literal>one</literal>,
                                 <para>This will execute
                                 <command>/bin/echo</command> with four
                                 arguments: <literal>one</literal>,


@@ -716,7 +720,7 @@ ExecStart=/bin/echo $ONE $TWO ${TWO}
                                 timeout for the service expires.
                                 If set to
                                 <option>always</option>, the service
                                 timeout for the service expires.
                                 If set to
                                 <option>always</option>, the service

-                                will be restarted regardless whether
+                                will be restarted regardless of whether

                                 it exited cleanly or not, got
                                 terminated abnormally by a signal or
                                 hit a timeout.</para>
                                 it exited cleanly or not, got
                                 terminated abnormally by a signal or
                                 hit a timeout.</para>


@@ -736,22 +740,36 @@ ExecStart=/bin/echo $ONE $TWO ${TWO}
                                 considered successful termination, in
                                 addition to the normal successful exit
                                 code 0 and the signals <constant>SIGHUP</constant>, <constant>SIGINT</constant>,
                                 considered successful termination, in
                                 addition to the normal successful exit
                                 code 0 and the signals <constant>SIGHUP</constant>, <constant>SIGINT</constant>,

-                                <constant>SIGTERM</constant> and <constant>SIGPIPE</constant>. Exit status
+                                <constant>SIGTERM</constant>, and <constant>SIGPIPE</constant>. Exit status

                                 definitions can either be numeric exit
                                 codes or termination signal names,
                                 definitions can either be numeric exit
                                 codes or termination signal names,

-                                separated by spaces. Example:
-                                <literal>SuccessExitStatus=1 2 8
-                                <constant>SIGKILL</constant></literal>, ensures that exit
-                                codes 1, 2, 8 and the termination
-                                signal <constant>SIGKILL</constant> are considered clean
-                                service terminations. This option may
-                                appear more than once in which case
-                                the list of successful exit statuses
-                                is merged. If the empty string is
-                                assigned to this option, the list is
-                                reset, all prior assignments of this
-                                option will have no
-                                effect.</para></listitem>
+                                separated by spaces. Signals will only
+                                be considered if the service does not implement
+                                a signal handler and exits as a direct result
+                                of receiving the signal. For example:
+                               <programlisting>SuccessExitStatus=1 2 8 <constant>SIGKILL</constant></programlisting>
+                               ensures that exit codes 1, 2, 8 and
+                               the termination signal
+                               <constant>SIGKILL</constant> are
+                               considered clean service terminations.
+                               </para>
+
+                               <para>Note that if a process has a
+                               signal handler installed and exits by
+                               calling
+                               <citerefentry><refentrytitle>_exit</refentrytitle><manvolnum>2</manvolnum></citerefentry>
+                               in response to a signal, the
+                               information about the signal is lost.
+                               Programs should instead perform cleanup and kill themselves with the same signal instead. See
+                               <ulink url="http://www.cons.org/cracauer/sigint.html">Proper handling of SIGINT/SIGQUIT — How to be a proper program</ulink>.</para>
+
+                               <para>This option may appear more than once
+                               in which case the list of successful
+                               exit statuses is merged. If the empty
+                               string is assigned to this option, the
+                               list is reset, all prior assignments
+                               of this option will have no
+                               effect.</para></listitem>

                         </varlistentry>
 
                         <varlistentry>
                         </varlistentry>
 
                         <varlistentry>