man: consolidate list of active unit states into a shared table

Avoids the need to maintain the same list over and over again, and
link it to the defition table in the implementation as a reminder
too

(cherry picked from commit 3509fe124d3a4fe2934028f83ae156ade050c8fe)

diff --git a/man/org.freedesktop.systemd1.xml b/man/org.freedesktop.systemd1.xml
index b0b45097e30a31bf04767e188cb21ed092246ce3..b08cbe1d0055ac93ae87af936ae3ef0c13e61feb 100644 (file)
--- a/man/org.freedesktop.systemd1.xml
+++ b/man/org.freedesktop.systemd1.xml
@@ -2520,18 +2520,9 @@ node /org/freedesktop/systemd1/unit/avahi_2ddaemon_2eservice {
       was already active).</para>
 
       <para><varname>ActiveState</varname> contains a state value that reflects whether the unit is currently
-      active or not. The following states are currently defined: <literal>active</literal>,
-      <literal>reloading</literal>, <literal>inactive</literal>, <literal>failed</literal>,
-      <literal>activating</literal>, and <literal>deactivating</literal>. <literal>active</literal> indicates
-      that unit is active (obviously...). <literal>reloading</literal> indicates that the unit is active and
-      currently reloading its configuration. <literal>inactive</literal> indicates that it is inactive and
-      the previous run was successful or no previous run has taken place yet. <literal>failed</literal>
-      indicates that it is inactive and the previous run was not successful (more information about the
-      reason for this is available on the unit type specific interfaces, for example for services in the
-      <varname>Result</varname> property, see below). <literal>activating</literal> indicates that the unit
-      has previously been inactive but is currently in the process of entering an active state. Conversely
-      <literal>deactivating</literal> indicates that the unit is currently in the process of
-      deactivation.</para>
+      active or not. The following states are currently defined:</para>
+
+      <xi:include href="unit-states.xml" xpointer="table"/>
 
       <para><varname>SubState</varname> encodes states of the same state machine that
       <varname>ActiveState</varname> covers, but knows more fine-grained states that are

diff --git a/man/systemctl.xml b/man/systemctl.xml
index 25b8930871b5293be9370d006cb42e91ef85945c..bea596536fc7d839fb3f2149ee11dd0b1068b006 100644 (file)
--- a/man/systemctl.xml
+++ b/man/systemctl.xml
@@ -96,12 +96,15 @@ To show all installed unit files use 'systemctl list-unit-files'.</programlistin
 
             <para>The LOAD column shows the load state, one of <constant>loaded</constant>,
             <constant>not-found</constant>, <constant>bad-setting</constant>, <constant>error</constant>,
-            <constant>masked</constant>. The ACTIVE columns shows the general unit state, one of
-            <constant>active</constant>, <constant>reloading</constant>, <constant>inactive</constant>,
-            <constant>failed</constant>, <constant>activating</constant>, <constant>deactivating</constant>. The SUB
-            column shows the unit-type-specific detailed state of the unit, possible values vary by unit type. The list
-            of possible LOAD, ACTIVE, and SUB states is not constant and new systemd releases may both add and remove
-            values. <programlisting>systemctl --state=help</programlisting> command may be used to display the
+            <constant>masked</constant>. The ACTIVE columns shows the general unit state, one of the
+            following:</para>
+
+            <xi:include href="unit-states.xml" xpointer="table"/>
+
+            <para>The SUB column shows the unit-type-specific detailed state of the unit, possible values
+            vary by unit type. The list of possible LOAD, ACTIVE, and SUB states is not constant and new
+            systemd releases may both add and remove values.
+            <programlisting>systemctl --state=help</programlisting> command may be used to display the
             current set of possible values.</para>
 
             <para>This is the default command.</para>

diff --git a/man/systemd.xml b/man/systemd.xml
index f4aa7e06cac821ca1c8e6da7d6186f12407a4d0b..47eb86678373d14f79d09da882b1781884acb757 100644 (file)
--- a/man/systemd.xml
+++ b/man/systemd.xml
@@ -93,21 +93,12 @@
     configuration files, whose syntax and basic set of options is
     described in
     <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
-    however some are created automatically from other configuration
-    files, dynamically from system state or programmatically at runtime.
-    Units may be "active" (meaning started, bound, plugged in, …,
-    depending on the unit type, see below), or "inactive" (meaning
-    stopped, unbound, unplugged, …), as well as in the process of
-    being activated or deactivated, i.e. between the two states (these
-    states are called "activating", "deactivating"). A special
-    "failed" state is available as well, which is very similar to
-    "inactive" and is entered when the service failed in some way
-    (process returned error code on exit, or crashed, an operation
-    timed out, or after too many restarts). If this state is entered,
-    the cause will be logged, for later reference. Note that the
-    various unit types may have a number of additional substates,
-    which are mapped to the five generalized unit states described
-    here.</para>
+    however some are created automatically from other configuration files, dynamically from system state or
+    programmatically at runtime. Units may be in a number of states, described in the following table. Note
+    that the various unit types may have a number of additional substates, which are mapped to the
+    generalized unit states described here.</para>
+
+    <xi:include href="unit-states.xml" xpointer="table"/>
 
     <para>The following unit types are available:</para>
 

diff --git a/man/unit-states.xml b/man/unit-states.xml
new file mode 100644 (file)
index 0000000..da42192
--- /dev/null
+++ b/man/unit-states.xml
@@ -0,0 +1,56 @@
+<?xml version="1.0"?>
+<!DOCTYPE refsect1 PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
+
+<!--
+  SPDX-License-Identifier: LGPL-2.1-or-later
+-->
+
+<refsect1>
+  <title/>
+
+  <table id="table">
+    <title>Unit ACTIVE states</title>
+    <tgroup cols='2'>
+      <colspec colname='state'/>
+      <colspec colname='description'/>
+      <thead>
+        <row>
+            <entry>State</entry>
+            <entry>Description</entry>
+        </row>
+      </thead>
+      <tbody>
+        <row>
+            <entry><varname>active</varname></entry>
+            <entry>Started, bound, plugged in, …, depending on the unit type.</entry>
+        </row>
+        <row>
+            <entry><varname>inactive</varname></entry>
+            <entry>Stopped, unbound, unplugged, …, depending on the unit type.</entry>
+        </row>
+        <row>
+            <entry><varname>failed</varname></entry>
+            <entry>Similar as <constant>inactive</constant>, but the unit failed in some way (process returned error code on exit, or crashed, an operation timed out, or after too many restarts).
+            </entry>
+        </row>
+        <row>
+            <entry><varname>activating</varname></entry>
+            <entry>Changing from <constant>inactive</constant> to <constant>active</constant>.</entry>
+        </row>
+        <row>
+            <entry><varname>deactivating</varname></entry>
+            <entry>Changing from <constant>active</constant> to <constant>inactive</constant>.</entry>
+        </row>
+        <row>
+            <entry><varname>maintenance</varname></entry>
+            <entry>Unit is <constant>inactive</constant> and a maintenance operation is in progress.</entry>
+        </row>
+        <row>
+            <entry><varname>reloading</varname></entry>
+            <entry>Unit is <constant>active</constant> and it is reloading its configuration.</entry>
+        </row>
+      </tbody>
+    </tgroup>
+  </table>
+
+</refsect1>

diff --git a/src/basic/unit-def.c b/src/basic/unit-def.c
index d03363bd379b1997b273059a5805212fab39f474..6b693891c96a633d0c7a0d00ab7ff840f302585a 100644 (file)
--- a/src/basic/unit-def.c
+++ b/src/basic/unit-def.c
@@ -104,6 +104,7 @@ static const char* const unit_load_state_table[_UNIT_LOAD_STATE_MAX] = {
 
 DEFINE_STRING_TABLE_LOOKUP(unit_load_state, UnitLoadState);
 
+/* Keep in sync with man/unit-states.xml */
 static const char* const unit_active_state_table[_UNIT_ACTIVE_STATE_MAX] = {
         [UNIT_ACTIVE]       = "active",
         [UNIT_RELOADING]    = "reloading",