Merge pull request #13207 from keszybz/symbolic-exit-code-names

Symbolic exit code names

2 files changed, 54 insertions, 16 deletions

diff --git a/man/systemd-analyze.xml b/man/systemd-analyze.xml
index 7112362ac5..8e9f24caac 100644
--- a/man/systemd-analyze.xml
+++ b/man/systemd-analyze.xml
@@ -86,6 +86,12 @@
     <cmdsynopsis>
       <command>systemd-analyze</command>
       <arg choice="opt" rep="repeat">OPTIONS</arg>
+      <arg choice="plain">exit-codes</arg>
+      <arg choice="opt" rep="repeat"><replaceable>CODE</replaceable></arg>
+    </cmdsynopsis>
+    <cmdsynopsis>
+      <command>systemd-analyze</command>
+      <arg choice="opt" rep="repeat">OPTIONS</arg>
       <arg choice="plain">condition</arg>
       <arg choice="plain"><replaceable>CONDITION</replaceable>…</arg>
     </cmdsynopsis>
@@ -366,6 +372,30 @@ $ eog targets.svg</programlisting>
     </refsect2>
 
     <refsect2>
+      <title><command>systemd-analyze exit-codes <optional><replaceable>CODE</replaceable>...</optional></command></title>
+
+      <para>This command prints a list of exit codes along with their "class", i.e. the source of the
+      definition (one of <literal>glibc</literal>, <literal>systemd</literal>, <literal>LSB</literal>, or
+      <literal>BSD</literal>), see the Process Exit Codes section in
+      <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
+      If no additional arguments are specified, all known codes are are shown. Otherwise, only the
+      definitions for the specified codes are shown.</para>
+
+      <example>
+        <title><command>Show some example exit code names</command></title>
+
+        <programlisting>$ systemd-analyze exit-codes 0 1 {63..65}
+NAME    CODE CLASS
+SUCCESS 0    glibc
+FAILURE 1    glibc
+-       63   -
+USAGE   64   BSD
+DATAERR 65   BSD
+</programlisting>
+      </example>
+    </refsect2>
+
+    <refsect2>
       <title><command>systemd-analyze condition <replaceable>CONDITION</replaceable>...</command></title>
 
       <para>This command will evaluate <varname noindex='true'>Condition*=...</varname> and
diff --git a/man/systemd.service.xml b/man/systemd.service.xml
index 90c1257f37..40ac052ba5 100644
--- a/man/systemd.service.xml
+++ b/man/systemd.service.xml
@@ -852,27 +852,35 @@
 
       <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>
+
+        <para>Note: <command>systemd-analyze exit-codes</command> may be used to list exit
+        codes and translate between numerical code values and names.</para></listitem>
       </varlistentry>
 
       <varlistentry>