Merge pull request #23414 from keszybz/analyze-vercmp

systemd-analyze compare-versions

1 files changed, 60 insertions, 2 deletions

diff --git a/man/systemd-analyze.xml b/man/systemd-analyze.xml
index 97290d479b..8061743c56 100644
--- a/man/systemd-analyze.xml
+++ b/man/systemd-analyze.xml
@@ -121,6 +121,14 @@
     <cmdsynopsis>
       <command>systemd-analyze</command>
       <arg choice="opt" rep="repeat">OPTIONS</arg>
+      <arg choice="plain">compare-versions</arg>
+      <arg choice="plain"><replaceable>VERSION1</replaceable></arg>
+      <arg choice="opt"><replaceable>OP</replaceable></arg>
+      <arg choice="plain"><replaceable>VERSION2</replaceable></arg>
+    </cmdsynopsis>
+    <cmdsynopsis>
+      <command>systemd-analyze</command>
+      <arg choice="opt" rep="repeat">OPTIONS</arg>
       <arg choice="plain">verify</arg>
       <arg choice="opt" rep="repeat"><replaceable>FILE</replaceable></arg>
     </cmdsynopsis>
@@ -548,6 +556,52 @@ NAutoVTs=8
     </refsect2>
 
     <refsect2>
+      <title><command>systemd-analyze compare-versions
+      <replaceable>VERSION1</replaceable>
+      <optional><replaceable>OP</replaceable></optional>
+      <replaceable>VERSION2</replaceable></command></title>
+
+      <para>This command has two distinct modes of operation, depending on whether the operator
+      <replaceable>OP</replaceable> is specified.</para>
+
+      <para>In the first mode — when <replaceable>OP</replaceable> is not specified — it will compare the two
+      version strings and print either <literal><replaceable>VERSION1</replaceable> &lt;
+      <replaceable>VERSION2</replaceable></literal>, or <literal><replaceable>VERSION1</replaceable> ==
+      <replaceable>VERSION2</replaceable></literal>, or <literal><replaceable>VERSION1</replaceable> &gt;
+      <replaceable>VERSION2</replaceable></literal> as appropriate.</para>
+
+      <para>The exit status is <constant>0</constant> if the versions are equal, <constant>11</constant> if
+      the version of the right is smaller, and <constant>12</constant> if the version of the left is
+      smaller. (This matches the convention used by <command>rpmdev-vercmp</command>.)</para>
+
+      <para>In the second mode — when <replaceable>OP</replaceable> is specified — it will compare the two
+      version strings using the operation <replaceable>OP</replaceable> and return <constant>0</constant>
+      (success) if they condition is satisfied, and <constant>1</constant> (failure)
+      otherwise. <constant>OP</constant> may be <command>lt</command>, <command>le</command>,
+      <command>eq</command>, <command>ne</command>, <command>ge</command>, <command>gt</command>. In this
+      mode, no output is printed.
+      (This matches the convention used by
+      <citerefentry project='die-net'><refentrytitle>dpkg</refentrytitle><manvolnum>1</manvolnum></citerefentry>
+      <option>--compare-versions</option>.)</para>
+
+      <example>
+        <title>Compare versions of a package</title>
+
+        <programlisting>
+$ systemd-analyze compare-versions systemd-250~rc1.fc36.aarch64 systemd-251.fc36.aarch64
+systemd-250~rc1.fc36.aarch64 &lt; systemd-251.fc36.aarch64
+$ echo $?
+12
+
+$ systemd-analyze compare-versions 1 lt 2; echo $?
+0
+$ systemd-analyze compare-versions 1 ge 2; echo $?
+1
+        </programlisting>
+      </example>
+    </refsect2>
+
+    <refsect2>
       <title><command>systemd-analyze verify <replaceable>FILE</replaceable>...</command></title>
 
       <para>This command will load unit files and print warnings if any errors are detected. Files specified
@@ -1197,8 +1251,12 @@ $ systemd-analyze verify /tmp/source:alias.service
   <refsect1>
     <title>Exit status</title>
 
-    <para>On success, 0 is returned, a non-zero failure code
-    otherwise.</para>
+    <para>For most commands, 0 is returned on success, and a non-zero failure code otherwise.</para>
+
+    <para>With the verb <command>compare-versions</command>, in the two-argument form,
+    <constant>12</constant>, <constant>0</constant>, <constant>11</constant> is returned if the second
+    version string is respectively larger, equal, or smaller to the first. In the three-argument form,
+    <constant>0</constant> or <constant>1</constant> if the condition is respectively true or false.</para>
   </refsect1>
 
   <xi:include href="common-variables.xml" />