man: systemd.service(5): clarify behavior of SuccessExitStatus

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

diff --git a/man/systemd.service.xml b/man/systemd.service.xml
index 27f069f6b2a5ccaabbefecc4071c37b9fa9b9fde..72b872beced11be7146da478c10c6dd3913b548e 100644 (file)
--- a/man/systemd.service.xml
+++ b/man/systemd.service.xml
@@ -392,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


@@ -429,11 +445,6 @@
                                 <programlisting>ExecStart=/bin/sh -c 'dmesg | tac'
                                 </programlisting>
 
                                 <programlisting>ExecStart=/bin/sh -c 'dmesg | tac'
                                 </programlisting>
 

-                                <para>Only select environment variables that
-                                are set for executed commands. See
-                                <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
-                                </para>
-

                                 <para>Example:</para>
                                 <programlisting>ExecStart=/bin/echo one ; /bin/echo "two two"
                                 </programlisting>
                                 <para>Example:</para>
                                 <programlisting>ExecStart=/bin/echo one ; /bin/echo "two two"
                                 </programlisting>


@@ -734,22 +745,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>