From 1e0d5eebf1da932a47c8e4c2728c2f008d09abca Mon Sep 17 00:00:00 2001
From: Lennart Poettering <lennart@poettering.net>
Date: Mon, 11 May 2020 10:36:28 +0200
Subject: man: clarify that exit status name mappings are unaffected by
 SuccessExitStatus=

Fixes: #15757

(Note there's quite some confusion regarding "exit status" vs. "exit
code" in the docs here. We should clean this up fully one day. This
change tries to fix some occasions of the wrong use, but not all.)
---
 man/systemd.service.xml | 36 +++++++++++++++++++++---------------
 1 file changed, 21 insertions(+), 15 deletions(-)

(limited to 'man/systemd.service.xml')

diff --git a/man/systemd.service.xml b/man/systemd.service.xml
index 86dee3b3f0..0cfd0853c6 100644
--- a/man/systemd.service.xml
+++ b/man/systemd.service.xml
@@ -845,35 +845,41 @@
 
       <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>,
+        process, will be considered successful termination, in addition to the normal successful exit status
+        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
+        numeric termination statuses, termination status 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 termination status 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>
+        <para>Note that this setting does not change the the mapping between numeric exit statuses and their
+        names, i.e. regardless how this setting is used 0 will still be mapped to <literal>SUCCESS</literal>
+        (and thus typically shown as <literal>0/SUCCESS</literal> in tool outputs) and 1 to
+        <literal>FAILURE</literal> (and thus typically shown as <literal>1/FAILURE</literal>), and so on. It
+        only controls what happens as effect of these exit statuses, and how it propagates to the state of
+        the service as a whole.</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>
 
         <example>
           <title>A service with with the <varname>SuccessExitStatus=</varname> setting</title>
 
           <programlisting>SuccessExitStatus=TEMPFAIL 250 SIGUSR1</programlisting>
 
-          <para>Exit codes 75 (<constant>TEMPFAIL</constant>), 250, and the termination signal
+          <para>Exit status 75 (<constant>TEMPFAIL</constant>), 250, and the termination signal
           <constant>SIGKILL</constant> are considered clean service terminations.</para>
         </example>
 
-        <para>Note: <command>systemd-analyze exit-status</command> may be used to list exit
-        codes and translate between numerical code values and names.</para></listitem>
+        <para>Note: <command>systemd-analyze exit-status</command> may be used to list exit statuses and
+        translate between numerical status values and names.</para></listitem>
       </varlistentry>
 
       <varlistentry>
-- 
cgit v1.2.1