Merge pull request #10088 from keszybz/man-systemctl-return

man: add a description of systemctl return codes

diff --git a/man/systemctl.xml b/man/systemctl.xml
index e12e50dc80be13c1df7995f2cd9ca5bb30765b9b..2bf20142c09c84e679dcaca470698e5097a5140c 100644 (file)
--- a/man/systemctl.xml
+++ b/man/systemctl.xml
@@ -1940,8 +1940,56 @@ Jan 12 10:46:45 example.com bluetoothd[8900]: gatt-time-server: Input/output err
   <refsect1>
     <title>Exit status</title>
 
-    <para>On success, 0 is returned, a non-zero failure
-    code otherwise.</para>
+    <para>On success, 0 is returned, a non-zero failure code otherwise.</para>
+
+    <para><command>systemctl</command> uses the return codes defined by LSB, as defined in
+    <ulink url="http://refspecs.linuxbase.org/LSB_3.0.0/LSB-PDA/LSB-PDA/iniscrptact.html">LSB 3.0.0</ulink>.
+    </para>
+
+    <table>
+      <title>LSB return codes</title>
+
+      <tgroup cols='3'>
+        <thead>
+          <row>
+            <entry>Value</entry>
+            <entry>Description in LSB</entry>
+            <entry>Use in systemd</entry>
+          </row>
+        </thead>
+        <tbody>
+          <row>
+            <entry><constant>0</constant></entry>
+            <entry>"program is running or service is OK"</entry>
+            <entry>unit is active</entry>
+          </row>
+          <row>
+            <entry><constant>1</constant></entry>
+            <entry>"program is dead and <filename>/var/run</filename> pid file exists"</entry>
+            <entry>unit <emphasis>not</emphasis> failed (used by <command>is-failed</command>)</entry>
+          </row>
+          <row>
+            <entry><constant>2</constant></entry>
+            <entry>"program is dead and <filename>/var/lock</filename> lock file exists"</entry>
+            <entry>unused</entry>
+          </row>
+          <row>
+            <entry><constant>3</constant></entry>
+            <entry>"program is not running"</entry>
+            <entry>unit is not active</entry>
+          </row>
+          <row>
+            <entry><constant>4</constant></entry>
+            <entry>"program or service status is unknown"</entry>
+            <entry>no such unit</entry>
+          </row>
+        </tbody>
+      </tgroup>
+    </table>
+
+    <para>The mapping of LSB service states to systemd unit states is imperfect, so it is better to
+    not rely on those return values but to look for specific unit states and substates instead.
+    </para>
   </refsect1>
 
   <refsect1>

diff --git a/man/systemd.special.xml b/man/systemd.special.xml
index 38006c6abd91a84145b05fbbaff476797f477844..0d25e40d03a911eccd268a6c1c788e7d36dbd231 100644 (file)
--- a/man/systemd.special.xml
+++ b/man/systemd.special.xml
@@ -596,14 +596,18 @@
           <listitem>
             <para>A special target unit that sets up all slice units (see
             <citerefentry><refentrytitle>systemd.slice</refentrytitle><manvolnum>5</manvolnum></citerefentry>
-            for details) that shall be active after boot. By default the generic
-            <filename>system.slice</filename> slice unit, as well as the root slice unit
-            <filename>-.slice</filename>, is pulled in and ordered before this unit (see
+            for details) that shall always be active after boot. By default the generic
+            <filename>system.slice</filename> slice unit as well as the root slice unit
+            <filename>-.slice</filename> are pulled in and ordered before this unit (see
             below).</para>
 
-            <para>It's a good idea to add <varname>WantedBy=slices.target</varname> lines to the
-            <literal>[Install]</literal> section of all slices units that may be installed
-            dynamically.</para>
+            <para>Adding slice units to <filename>slices.target</filename> is generally not
+            necessary. Instead, when some unit that uses <varname>Slice=</varname> is started, the
+            specified slice will be started automatically. Adding
+            <varname>WantedBy=slices.target</varname> lines to the <literal>[Install]</literal>
+            section should only be done for units that need to be always active. In that case care
+            needs to be taken to avoid creating a loop through the automatic dependencies on
+            "parent" slices.</para>
           </listitem>
         </varlistentry>
         <varlistentry>