pid1,systemctl: allow symbolic exit code names

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

diff --git a/man/systemd.service.xml b/man/systemd.service.xml
index 4ff009e7732f224b673825b1dfb763a808ffb73e..06116df1b035d29ab30dda65c79cb8e83605b6a5 100644 (file)
--- a/man/systemd.service.xml
+++ b/man/systemd.service.xml
@@ -427,6 +427,26 @@
         </listitem>
       </varlistentry>
 
+      <varlistentry>
+        <term><varname>ExecCondition=</varname></term>
+        <listitem><para>Optional commands that are executed before the command(s) in <varname>ExecStartPre=</varname>.
+        Syntax is the same as for <varname>ExecStart=</varname>, except that multiple command lines are allowed and the
+        commands are executed one after the other, serially.</para>
+
+        <para>The behavior is like an <varname>ExecStartPre=</varname> and condition check hybrid: when an
+        <varname>ExecCondition=</varname> command exits with exit code 1 through 254 (inclusive), the remaining
+        commands are skipped and the unit is <emphasis>not</emphasis> marked as failed. However, if an
+        <varname>ExecCondition=</varname> command exits with 255 or abnormally (e.g. timeout, killed by a
+        signal, etc.), the unit will be considered failed (and remaining commands will be skipped). Exit code of 0 or
+        those matching <varname>SuccessExitStatus=</varname> will continue execution to the next command(s).</para>
+
+        <para>The same recommendations about not running long-running processes in <varname>ExecStartPre=</varname>
+        also applies to <varname>ExecCondition=</varname>. <varname>ExecCondition=</varname> will also run the commands
+        in <varname>ExecStopPost=</varname>, as part of stopping the service, in the case of any non-zero or abnormal
+        exits, like the ones described above.</para>
+        </listitem>
+      </varlistentry>
+
       <varlistentry>
         <term><varname>ExecReload=</varname></term>
         <listitem><para>Commands to execute to trigger a configuration
@@ -832,27 +852,32 @@
 
       <varlistentry>
         <term><varname>SuccessExitStatus=</varname></term>
-        <listitem><para>Takes a list of exit status definitions that,
-        when returned by the main service process, will be 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 definitions can
-        either be numeric exit codes or termination signal names,
-        separated by spaces. For example:
-
-        <programlisting>SuccessExitStatus=1 2 8 SIGKILL</programlisting>
-
-        ensures that exit codes 1, 2, 8 and
-        the termination signal <constant>SIGKILL</constant> are
-        considered clean service terminations.
-        </para>
+        <listitem><para>Takes a list of exit status definitions that, when returned by the main service
+        process, will be 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 definitions can be
+        numeric exit codes, termination code names, or termination signal names, separated by spaces. See the
+        Process Exit Codes section in
+        <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry> for
+        a list of termination codes names (for this setting only the part without the
+        <literal>EXIT_</literal> or <literal>EX_</literal> prefix should be used). See
+        <citerefentry project='man-pages'><refentrytitle>signal</refentrytitle><manvolnum>7</manvolnum></citerefentry> for
+        a list of signal names.</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>
+        effect.</para>
+
+        <example>
+          <title>A service with with the the <varname>SuccessExitStatus=</varname> setting</title>
+
+          <programlisting>SuccessExitStatus=TEMPFAIL 250 SIGUSR1</programlisting>
+
+          <para>Exit codes 75 (<constant>TEMPFAIL</constant>), 250, and the termination signal
+          <constant>SIGKILL</constant> are considered clean service terminations.</para>
+        </example></listitem>
       </varlistentry>
 
       <varlistentry>