man: provide a basic guide to the `systemctl status` output (#4950)

 - Show example of all `systemctl status` output and documents what possible
   "Loaded:", "Active" and "Enabled" values mean.

 - Documents what different colors of the dot mean.

 - Documents "gotcha" with load-on-demand behavior which will report units as
   "loaded" even if they are only loaded to show their status.
   (From @poettering: https://github.com/systemd/systemd/issues/5063#issuecomment-272115024 )

diff --git a/man/systemctl.xml b/man/systemctl.xml
index 1440d71..391e5df 100644 (file)
--- a/man/systemctl.xml
+++ b/man/systemctl.xml
@@ -876,6 +876,56 @@ kobject-uevent 1 systemd-udevd-kernel.socket systemd-udevd.service
             a similar filter for messages and might be more
             convenient.
             </para>
+
+            <para>Systemd implicitly loads units as necessary, so just running the <command>status</command> will
+            attempt to load a file. The command is thus not useful for determining if something was already loaded or
+            not.  The units may possibly also be quickly unloaded after the operation is completed if there's no reason
+            to keep it in memory thereafter.
+            </para>
+
+            <example>
+              <title>Example output from systemctl status </title>
+
+              <programlisting>$ systemctl status bluetooth
+● bluetooth.service - Bluetooth service
+   Loaded: loaded (/lib/systemd/system/bluetooth.service; enabled; vendor preset: enabled)
+   Active: active (running) since Wed 2017-01-04 13:54:04 EST; 1 weeks 0 days ago
+     Docs: man:bluetoothd(8)
+ Main PID: 930 (bluetoothd)
+   Status: "Running"
+    Tasks: 1
+   Memory: 648.0K
+      CPU: 435ms
+   CGroup: /system.slice/bluetooth.service
+           └─930 /usr/lib/bluetooth/bluetoothd
+
+Jan 12 10:46:45 example.com bluetoothd[8900]: Not enough free handles to register service
+Jan 12 10:46:45 example.com.com bluetoothd[8900]: Current Time Service could not be registered
+Jan 12 10:46:45 example.com.com bluetoothd[8900]: gatt-time-server: Input/output error (5)
+</programlisting>
+
+            <para>The dot ("●") uses color on supported terminals to summarize the unit state at a glance. White
+            indicates an <literal>inactive</literal> or <literal>deactivating</literal> state. Red indicates a
+            <literal>failed</literal> or <literal>error</literal> state and green indicates an
+            <literal>active</literal>, <literal>reloading</literal> or <literal>activating</literal> state.
+            </para>
+
+            <para>The "Loaded:" line in the output will show <literal>loaded</literal> if the unit has been loaded into
+            memory. Other possible values for "Loaded:" include: <literal>error</literal> if there was a problem
+            loading it, <literal>not-found</literal>, and <literal>masked</literal>. Along with showing the path to
+            the unit file, this line will also show the enablement state.  Enabled commands start at boot.  See the
+            full table of possible enablement states — including the definition of <literal>masked</literal> — in the
+            documentation for the <command>is-enabled</command> command.
+            </para>
+
+            <para>The "Active:" line shows active state.  The value is usually <literal>active</literal> or
+            <literal>inactive</literal>. Active could mean started, bound, plugged in, etc depending on the unit type.
+            The unit could also be in process of changing states, reporting a state of <literal>activating</literal> or
+            <literal>deactivating</literal>. A special <literal>failed</literal> state is entered when the service
+            failed in some way, such as a crash, exiting with an error code or timing out. If the failed state is
+            entered the cause will be logged for later reference.</para>
+            </example>
+
           </listitem>
         </varlistentry>
         <varlistentry>