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

diff --git a/man/org.freedesktop.systemd1.xml b/man/org.freedesktop.systemd1.xml
index aa4f69deb19da07b7d2bb02911a257fc2c9bb614..dd144a6cba07e037776f01a4cfb6ed94f99c3a93 100644 (file)
--- a/man/org.freedesktop.systemd1.xml
+++ b/man/org.freedesktop.systemd1.xml
@@ -2550,18 +2550,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 11da7a9b73cef26bf33acffa4b652152d06440d5..5820478335bfe62f05a0deb5f956c33dd962eee0 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 af1681352e8d7c7b6424932778c3b0d234ab2896..71da1ec8f1d1793fab79ca160a577d5f195ea3b7 100644 (file)
--- a/man/systemd.xml
+++ b/man/systemd.xml
@@ -95,16 +95,11 @@
     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. Units may also be in a special transient state for a time, to indicate
-    that some operation is being performed on them, before reverting to the previous state, such as
-    "maintenance", "reloading" or "refreshing". 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>
+    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..436e4fa
--- /dev/null
+++ b/man/unit-states.xml
@@ -0,0 +1,61 @@
+<?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>
+        <row>
+            <entry><varname>refreshing</varname></entry>
+            <entry>Unit is <constant>active</constant> and a new mount is being activated in its namespace.
+            </entry>
+        </row>
+      </tbody>
+    </tgroup>
+  </table>
+
+</refsect1>

diff --git a/src/basic/unit-def.c b/src/basic/unit-def.c
index e3292a8a4471c83f1b6e2f0d72f40be0462b70ac..03dc663b9a6db9d6eec2f1c6f65e6ff0e2cd63eb 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",