From: Lennart Poettering <lennart@poettering.net>
Date: Mon, 24 Jun 2019 12:51:52 +0000 (+0200)
Subject: doc: make clear that --system and --user only make sense with --test
X-Git-Tag: v243-rc1~245^2~2
X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=cd69e88ba3a692618048117b26fc9ea339aa1845;p=thirdparty%2Fsystemd.git

doc: make clear that --system and --user only make sense with --test

Fixes: #12843
---

diff --git a/man/systemd.xml b/man/systemd.xml
index c51f0bf4d1f..7ede4e3f403 100644
--- a/man/systemd.xml
+++ b/man/systemd.xml
@@ -70,8 +70,13 @@
       <varlistentry>
         <term><option>--test</option></term>
 
-        <listitem><para>Determine startup sequence, dump it and exit.
-        This is an option useful for debugging only.</para></listitem>
+        <listitem><para>Determine the initial start-up transaction (i.e. the list of jobs enqueued at
+        start-up), dump it and exit. This option is useful for debugging only. Note that during regular
+        service manager start-up further units might be started than this operation shows, because hardware,
+        socket, bus or other kinds of activation might add additional jobs. Use <option>--system</option> to
+        request the initial transaction of the system service manager (this is also the implied default),
+        combine with <option>--user</option> to request the initial transaction of the per-user service
+        manager instead.</para></listitem>
       </varlistentry>
       <varlistentry>
         <term><option>--dump-configuration-items</option></term>
@@ -94,23 +99,20 @@
         not specified, defaults to
         <filename>default.target</filename>.</para></listitem>
       </varlistentry>
+
       <varlistentry>
         <term><option>--system</option></term>
         <term><option>--user</option></term>
 
-        <listitem><para>For <option>--system</option>, tell systemd to
-        run a system instance, even if the process ID is not 1, i.e.
-        systemd is not run as init process. <option>--user</option>
-        does the opposite, running a user instance even if the process
-        ID is 1. Normally, it should not be necessary to pass these
-        options, as systemd automatically detects the mode it is
-        started in. These options are hence of little use except for
-        debugging. Note that it is not supported booting and
-        maintaining a full system with systemd running in
-        <option>--system</option> mode, but PID not 1. In practice,
-        passing <option>--system</option> explicitly is only useful in
-        conjunction with <option>--test</option>.</para></listitem>
+        <listitem><para>When used in conjunction with <option>--test</option>, selects whether to calculate
+        the initial transaction for the system instance or for a per-user instance. These options have no
+        effect when invoked without <option>--test</option>, as during regular
+        (i.e. non-<option>--test</option>) invocations the service manager will automatically detect whether
+        it shall operate in system or per-user mode, by checking whether the PID it is run as is 1 or
+        not. Note that it is not supported booting and maintaining a system with the service manager running
+        in <option>--system</option> mode but with a PID other than 1.</para></listitem>
       </varlistentry>
+
       <varlistentry>
         <term><option>--dump-core</option></term>
 
diff --git a/src/core/main.c b/src/core/main.c
index a94e6caf858..3a41573ef04 100644
--- a/src/core/main.c
+++ b/src/core/main.c
@@ -1157,13 +1157,13 @@ static int help(void) {
                "Starts up and maintains the system or user services.\n\n"
                "  -h --help                      Show this help\n"
                "     --version                   Show version\n"
-               "     --test                      Determine startup sequence, dump it and exit\n"
+               "     --test                      Determine initial transaction, dump it and exit\n"
+               "     --system                    In combination with --test: operate as system service manager\n"
+               "     --user                      In combination with --test: operate as per-user service manager\n"
                "     --no-pager                  Do not pipe output into a pager\n"
                "     --dump-configuration-items  Dump understood unit configuration items\n"
                "     --dump-bus-properties       Dump exposed bus properties\n"
                "     --unit=UNIT                 Set default unit\n"
-               "     --system                    Run a system instance, even if PID != 1\n"
-               "     --user                      Run a user instance\n"
                "     --dump-core[=BOOL]          Dump core on crash\n"
                "     --crash-vt=NR               Change to specified VT on crash\n"
                "     --crash-reboot[=BOOL]       Reboot on crash\n"