systemctl: replace the three job mode options by a single --job-mode= option

Also, expose the new "flush" job mode this way.

3 files changed, 70 insertions, 57 deletions

diff --git a/man/systemctl.xml b/man/systemctl.xml
index 33a293581c..58b2c2ad96 100644
--- a/man/systemctl.xml
+++ b/man/systemctl.xml
@@ -195,18 +195,6 @@ systemctl start foo
       </varlistentry>
 
       <varlistentry>
-        <term><option>--fail</option></term>
-
-        <listitem>
-          <para>If the requested operation conflicts with a pending
-          unfinished job, fail the command. If this is not specified,
-          the requested operation will replace the pending job, if
-          necessary. Do not confuse with
-          <option>--failed</option>.</para>
-        </listitem>
-      </varlistentry>
-
-      <varlistentry>
         <term><option>--show-types</option></term>
 
         <listitem>
@@ -215,27 +203,58 @@ systemctl start foo
       </varlistentry>
 
       <varlistentry>
-        <term><option>--irreversible</option></term>
+        <term><option>--job-mode=</option></term>
 
         <listitem>
-          <para>Mark this transaction's jobs as irreversible. This prevents
-          future conflicting transactions from replacing these jobs.
-          The jobs can still be cancelled using the <command>cancel</command>
-          command.</para>
+        <para>When queuing a new job, control how to deal with already
+        queued jobs. Takes one of <literal>fail</literal>,
+        <literal>replace</literal>,
+        <literal>replace-irreversibly</literal>,
+        <literal>isolate</literal>,
+        <literal>ignore-dependencies</literal>,
+        <literal>ignore-requirements</literal> or
+        <literal>flush</literal>. Defaults to
+        <literal>replace</literal>, except when the
+        <command>isolate</command> command is used which implies the
+        <literal>isolate</literal> job mode.</para>
+
+        <para>If <literal>fail</literal> is specified and a requested
+        operation conflicts with a pending job (more specifically:
+        causes an already pending start job to be reversed into a stop
+        job or vice versa), cause the operation to fail.</para>
+
+        <para>If <literal>replace</literal> (the default) is
+        specified, any conflicting pending job will be replaced, as
+        necessary.</para>
+
+        <para>If <literal>replace-irreversibly</literal> is specified,
+        operate like <literal>replace</literal>, but also mark the new
+        jobs as irreversible. This prevents future conflicting
+        transactions from replacing these jobs. The jobs can still be
+        cancelled using the <command>cancel</command> command.</para>
+
+        <para><literal>isolate</literal> is only valid for start
+        operations and causes all other units to be stopped when the
+        specified unit is started. This mode is always used when the
+        <command>isolate</command> command is used.</para>
+
+        <para><literal>flush</literal> will cause all queued jobs to
+        be canceled when the new job is enqueued.</para>
+
+        <para>If <literal>ignore-dependencies</literal> is specified,
+        then all unit dependencies are ignored for this new job and
+        the operation is executed immediately. If passed, no required
+        units of the unit passed will be pulled in, and no ordering
+        dependencies will be honored. This is mostly a debugging and
+        rescue tool for the administrator and should not be used by
+        applications.</para>
+
+        <para><literal>ignore-requirements</literal> is similar to
+        <literal>ignore-dependencies</literal> but only causes the
+        requirement dependencies to be ignored, the ordering
+        dependencies will still be honoured.</para>
         </listitem>
-      </varlistentry>
-
-      <varlistentry>
-        <term><option>--ignore-dependencies</option></term>
 
-        <listitem>
-          <para>When enqueuing a new job, ignore all its dependencies
-          and execute it immediately. If passed, no required units of
-          the unit passed will be pulled in, and no ordering
-          dependencies will be honored. This is mostly a debugging and
-          rescue tool for the administrator and should not be used by
-          applications.</para>
-        </listitem>
       </varlistentry>
 
       <varlistentry>
diff --git a/man/systemd.unit.xml b/man/systemd.unit.xml
index b43fa1369e..2c8bfbef70 100644
--- a/man/systemd.unit.xml
+++ b/man/systemd.unit.xml
@@ -674,28 +674,20 @@
                                 <listitem><para>Takes a value of
                                 <literal>fail</literal>,
                                 <literal>replace</literal>,
-                                <literal>replace-irreversibly</literal>
+                                <literal>replace-irreversibly</literal>,
+                                <literal>isolate</literal>,
+                                <literal>flush</literal>,
+                                <literal>ignore-dependencies</literal>
                                 or
-                                <literal>isolate</literal>. Defaults
+                                <literal>ignore-requirements</literal>. Defaults
                                 to
                                 <literal>replace</literal>. Specifies
                                 how the units listed in
                                 <varname>OnFailure=</varname> will be
-                                enqueued. If set to
-                                <literal>fail</literal> and
-                                contradicting jobs are already queued,
-                                cause the activation to fail. If set
-                                to <literal>replace</literal> and
-                                contradicting jobs area already
-                                queued, replace
-                                those. <literal>replace-irreversibly</literal>
-                                is similar to
-                                <literal>replace</literal>, however,
-                                creates jobs that cannot be reversed
-                                unless they finished or are explicitly
-                                canceled. <literal>isolate</literal>
-                                may be used to terminate all other
-                                units but the specified one. If
+                                enqueued. See
+                                <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>'s
+                                <option>--job-mode=</option> option
+                                for details on the possible values. If
                                 this is set to
                                 <literal>isolate</literal>, only a
                                 single unit may be listed in
diff --git a/src/systemctl/systemctl.c b/src/systemctl/systemctl.c
index 3fcc066a9f..23399c16c6 100644
--- a/src/systemctl/systemctl.c
+++ b/src/systemctl/systemctl.c
@@ -4671,14 +4671,10 @@ static int systemctl_help(void) {
                "  -a --all            Show all loaded units/properties, including dead/empty\n"
                "                      ones. To list all units installed on the system, use\n"
                "                      the 'list-unit-files' command instead.\n"
-               "     --reverse        Show reverse dependencies with 'list-dependencies'\n"
                "  -l --full           Don't ellipsize unit names on output\n"
-               "     --fail           When queueing a new job, fail if conflicting jobs are\n"
-               "                      pending\n"
-               "     --irreversible   When queueing a new job, make sure it cannot be implicitly\n"
-               "                      cancelled\n"
-               "     --ignore-dependencies\n"
-               "                      When queueing a new job, ignore all its dependencies\n"
+               "     --reverse        Show reverse dependencies with 'list-dependencies'\n"
+               "     --job-mode=MODE  Specify how to deal with already queued jobs, when\n"
+               "                      queueing a new job\n"
                "     --show-types     When showing sockets, explicitly show their type\n"
                "  -i --ignore-inhibitors\n"
                "                      When shutting down or sleeping, ignore inhibitors\n"
@@ -4880,7 +4876,8 @@ static int systemctl_parse_argv(int argc, char *argv[]) {
                 ARG_RUNTIME,
                 ARG_FORCE,
                 ARG_PLAIN,
-                ARG_STATE
+                ARG_STATE,
+                ARG_JOB_MODE
         };
 
         static const struct option options[] = {
@@ -4895,9 +4892,10 @@ static int systemctl_parse_argv(int argc, char *argv[]) {
                 { "show-types",          no_argument,       NULL, ARG_SHOW_TYPES          },
                 { "failed",              no_argument,       NULL, ARG_FAILED              }, /* compatibility only */
                 { "full",                no_argument,       NULL, 'l'                     },
-                { "fail",                no_argument,       NULL, ARG_FAIL                },
-                { "irreversible",        no_argument,       NULL, ARG_IRREVERSIBLE        },
-                { "ignore-dependencies", no_argument,       NULL, ARG_IGNORE_DEPENDENCIES },
+                { "job-mode",            required_argument, NULL, ARG_JOB_MODE            },
+                { "fail",                no_argument,       NULL, ARG_FAIL                }, /* compatibility only */
+                { "irreversible",        no_argument,       NULL, ARG_IRREVERSIBLE        }, /* compatibility only */
+                { "ignore-dependencies", no_argument,       NULL, ARG_IGNORE_DEPENDENCIES }, /* compatibility only */
                 { "ignore-inhibitors",   no_argument,       NULL, 'i'                     },
                 { "user",                no_argument,       NULL, ARG_USER                },
                 { "system",              no_argument,       NULL, ARG_SYSTEM              },
@@ -5035,6 +5033,10 @@ static int systemctl_parse_argv(int argc, char *argv[]) {
                         arg_show_types = true;
                         break;
 
+                case ARG_JOB_MODE:
+                        arg_job_mode = optarg;
+                        break;
+
                 case ARG_FAIL:
                         arg_job_mode = "fail";
                         break;