man: document which special "systemctl" commands are synchronous and which asynchronous.
This documents the status quo, clarifying when we are synchronous and when asynchronous by default and when --no-block is support to force asynchronous operation. See: #6479
This commit is contained in:
Lennart Poettering
parent
d13f5e164e
commit
6324a8a727
|
|
@ -407,8 +407,7 @@
|
||||||
<term><option>--no-wall</option></term>
|
<term><option>--no-wall</option></term>
|
||||||
|
|
||||||
<listitem>
|
<listitem>
|
||||||
<para>Do not send wall message before halt, power-off,
|
<para>Do not send wall message before halt, power-off and reboot.</para>
|
||||||
reboot.</para>
|
|
||||||
</listitem>
|
</listitem>
|
||||||
</varlistentry>
|
</varlistentry>
|
||||||
|
|
||||||
|
|
@ -525,7 +524,7 @@
|
||||||
<option>--force</option> twice with any of these operations might result in data loss. Note that when
|
<option>--force</option> twice with any of these operations might result in data loss. Note that when
|
||||||
<option>--force</option> is specified twice the selected operation is executed by
|
<option>--force</option> is specified twice the selected operation is executed by
|
||||||
<command>systemctl</command> itself, and the system manager is not contacted. This means the command should
|
<command>systemctl</command> itself, and the system manager is not contacted. This means the command should
|
||||||
succeed even when the system manager hangs or crashed.</para>
|
succeed even when the system manager has crashed.</para>
|
||||||
</listitem>
|
</listitem>
|
||||||
</varlistentry>
|
</varlistentry>
|
||||||
|
|
||||||
|
|
@ -533,11 +532,9 @@
|
||||||
<term><option>--message=</option></term>
|
<term><option>--message=</option></term>
|
||||||
|
|
||||||
<listitem>
|
<listitem>
|
||||||
<para>When used with <command>halt</command>,
|
<para>When used with <command>halt</command>, <command>poweroff</command> or <command>reboot</command>, set a
|
||||||
<command>poweroff</command>, <command>reboot</command> or
|
short message explaining the reason for the operation. The message will be logged together with the default
|
||||||
<command>kexec</command>, set a short message explaining the reason
|
shutdown message.</para>
|
||||||
for the operation. The message will be logged together with the
|
|
||||||
default shutdown message.</para>
|
|
||||||
</listitem>
|
</listitem>
|
||||||
</varlistentry>
|
</varlistentry>
|
||||||
|
|
||||||
|
|
@ -1690,8 +1687,8 @@ Jan 12 10:46:45 example.com bluetoothd[8900]: gatt-time-server: Input/output err
|
||||||
<term><command>default</command></term>
|
<term><command>default</command></term>
|
||||||
|
|
||||||
<listitem>
|
<listitem>
|
||||||
<para>Enter default mode. This is mostly equivalent to
|
<para>Enter default mode. This is equivalent to <command>systemctl isolate default.target</command>. This
|
||||||
<command>isolate default.target</command>.</para>
|
operation is blocking by default, use <option>--no-block</option> to request asynchronous behavior.</para>
|
||||||
</listitem>
|
</listitem>
|
||||||
</varlistentry>
|
</varlistentry>
|
||||||
|
|
||||||
|
|
@ -1699,72 +1696,77 @@ Jan 12 10:46:45 example.com bluetoothd[8900]: gatt-time-server: Input/output err
|
||||||
<term><command>rescue</command></term>
|
<term><command>rescue</command></term>
|
||||||
|
|
||||||
<listitem>
|
<listitem>
|
||||||
<para>Enter rescue mode. This is mostly equivalent to
|
<para>Enter rescue mode. This is equivalent to <command>systemctl isolate rescue.target</command>. This
|
||||||
<command>isolate rescue.target</command>, but also prints a
|
operation is blocking by default, use <option>--no-block</option> to request asynchronous behavior.</para>
|
||||||
wall message to all users.</para>
|
|
||||||
</listitem>
|
</listitem>
|
||||||
</varlistentry>
|
</varlistentry>
|
||||||
<varlistentry>
|
<varlistentry>
|
||||||
<term><command>emergency</command></term>
|
<term><command>emergency</command></term>
|
||||||
|
|
||||||
<listitem>
|
<listitem>
|
||||||
<para>Enter emergency mode. This is mostly equivalent to
|
<para>Enter emergency mode. This is equivalent to <command>systemctl isolate
|
||||||
<command>isolate emergency.target</command>, but also prints
|
emergency.target</command>. This operation is blocking by default, use <option>--no-block</option> to
|
||||||
a wall message to all users.</para>
|
request asynchronous behavior.</para>
|
||||||
</listitem>
|
</listitem>
|
||||||
</varlistentry>
|
</varlistentry>
|
||||||
<varlistentry>
|
<varlistentry>
|
||||||
<term><command>halt</command></term>
|
<term><command>halt</command></term>
|
||||||
|
|
||||||
<listitem>
|
<listitem>
|
||||||
<para>Shut down and halt the system. This is mostly equivalent to <command>start halt.target
|
<para>Shut down and halt the system. This is mostly equivalent to <command>systemctl start halt.target
|
||||||
--job-mode=replace-irreversibly</command>, but also prints a wall message to all users. If combined with
|
--job-mode=replace-irreversibly --no-block</command>, but also prints a wall message to all users. This command is
|
||||||
<option>--force</option>, shutdown of all running services is skipped, however all processes are killed and
|
asynchronous; it will return after the halt operation is enqueued, without waiting for it to complete. Note
|
||||||
all file systems are unmounted or mounted read-only, immediately followed by the system halt. If
|
that this operation will simply halt the OS kernel after shutting down, leaving the hardware powered
|
||||||
<option>--force</option> is specified twice, the operation is immediately executed without terminating any
|
on. Use <command>systemctl poweroff</command> for powering off the system (see below).</para>
|
||||||
processes or unmounting any file systems. This may result in data loss. Note that when
|
|
||||||
<option>--force</option> is specified twice the halt operation is executed by
|
<para>If combined with <option>--force</option>, shutdown of all running services is skipped, however all
|
||||||
<command>systemctl</command> itself, and the system manager is not contacted. This means the command should
|
processes are killed and all file systems are unmounted or mounted read-only, immediately followed by the
|
||||||
succeed even when the system manager hangs or crashed.</para>
|
system halt. If <option>--force</option> is specified twice, the operation is immediately executed without
|
||||||
|
terminating any processes or unmounting any file systems. This may result in data loss. Note that when
|
||||||
|
<option>--force</option> is specified twice the halt operation is executed by <command>systemctl</command>
|
||||||
|
itself, and the system manager is not contacted. This means the command should succeed even when the system
|
||||||
|
manager has crashed.</para>
|
||||||
</listitem>
|
</listitem>
|
||||||
</varlistentry>
|
</varlistentry>
|
||||||
<varlistentry>
|
<varlistentry>
|
||||||
<term><command>poweroff</command></term>
|
<term><command>poweroff</command></term>
|
||||||
|
|
||||||
<listitem>
|
<listitem>
|
||||||
<para>Shut down and power-off the system. This is mostly equivalent to <command>start poweroff.target
|
<para>Shut down and power-off the system. This is mostly equivalent to <command>systemctl start
|
||||||
--job-mode=replace-irreversibly</command>, but also prints a wall message to all users. If combined with
|
poweroff.target --job-mode=replace-irreversibly --no-block</command>, but also prints a wall message to all
|
||||||
<option>--force</option>, shutdown of all running services is skipped, however all processes are killed and
|
users. This command is asynchronous; it will return after the power-off operation is enqueued, without
|
||||||
all file systems are unmounted or mounted read-only, immediately followed by the powering off. If
|
waiting for it to complete.</para>
|
||||||
<option>--force</option> is specified twice, the operation is immediately executed without terminating any
|
|
||||||
processes or unmounting any file systems. This may result in data loss. Note that when
|
<para>If combined with <option>--force</option>, shutdown of all running services is skipped, however all
|
||||||
|
processes are killed and all file systems are unmounted or mounted read-only, immediately followed by the
|
||||||
|
powering off. If <option>--force</option> is specified twice, the operation is immediately executed without
|
||||||
|
terminating any processes or unmounting any file systems. This may result in data loss. Note that when
|
||||||
<option>--force</option> is specified twice the power-off operation is executed by
|
<option>--force</option> is specified twice the power-off operation is executed by
|
||||||
<command>systemctl</command> itself, and the system manager is not contacted. This means the command should
|
<command>systemctl</command> itself, and the system manager is not contacted. This means the command should
|
||||||
succeed even when the system manager hangs or crashed.</para>
|
succeed even when the system manager has crashed.</para>
|
||||||
</listitem>
|
</listitem>
|
||||||
</varlistentry>
|
</varlistentry>
|
||||||
<varlistentry>
|
<varlistentry>
|
||||||
<term><command>reboot <optional><replaceable>arg</replaceable></optional></command></term>
|
<term><command>reboot <optional><replaceable>arg</replaceable></optional></command></term>
|
||||||
|
|
||||||
<listitem>
|
<listitem>
|
||||||
<para>Shut down and reboot the system. This is mostly equivalent to <command>start reboot.target
|
<para>Shut down and reboot the system. This is mostly equivalent to <command>systemctl start reboot.target
|
||||||
--job-mode=replace-irreversibly</command>, but also prints a wall message to all users. If combined with
|
--job-mode=replace-irreversibly --no-block</command>, but also prints a wall message to all users. This
|
||||||
<option>--force</option>, shutdown of all running services is skipped, however all processes are killed and
|
command is asynchronous; it will return after the reboot operation is enqueued, without waiting for it to
|
||||||
all file systems are unmounted or mounted read-only, immediately followed by the reboot. If
|
complete.</para>
|
||||||
<option>--force</option> is specified twice, the operation is immediately executed without terminating any
|
|
||||||
processes or unmounting any file systems. This may result in data loss. Note that when
|
<para>If combined with <option>--force</option>, shutdown of all running services is skipped, however all
|
||||||
|
processes are killed and all file systems are unmounted or mounted read-only, immediately followed by the
|
||||||
|
reboot. If <option>--force</option> is specified twice, the operation is immediately executed without
|
||||||
|
terminating any processes or unmounting any file systems. This may result in data loss. Note that when
|
||||||
<option>--force</option> is specified twice the reboot operation is executed by
|
<option>--force</option> is specified twice the reboot operation is executed by
|
||||||
<command>systemctl</command> itself, and the system manager is not contacted. This means the command should
|
<command>systemctl</command> itself, and the system manager is not contacted. This means the command should
|
||||||
succeed even when the system manager hangs or crashed.</para>
|
succeed even when the system manager has crashed.</para>
|
||||||
|
|
||||||
<para>If the optional argument
|
<para>If the optional argument <replaceable>arg</replaceable> is given, it will be passed as the optional
|
||||||
<replaceable>arg</replaceable> is given, it will be passed
|
argument to the <citerefentry><refentrytitle>reboot</refentrytitle><manvolnum>2</manvolnum></citerefentry>
|
||||||
as the optional argument to the
|
system call. The value is architecture and firmware specific. As an example, <literal>recovery</literal>
|
||||||
<citerefentry><refentrytitle>reboot</refentrytitle><manvolnum>2</manvolnum></citerefentry>
|
might be used to trigger system recovery, and <literal>fota</literal> might be used to trigger a
|
||||||
system call. The value is architecture and firmware
|
|
||||||
specific. As an example, <literal>recovery</literal> might
|
|
||||||
be used to trigger system recovery, and
|
|
||||||
<literal>fota</literal> might be used to trigger a
|
|
||||||
<quote>firmware over the air</quote> update.</para>
|
<quote>firmware over the air</quote> update.</para>
|
||||||
</listitem>
|
</listitem>
|
||||||
</varlistentry>
|
</varlistentry>
|
||||||
|
|
@ -1773,13 +1775,14 @@ Jan 12 10:46:45 example.com bluetoothd[8900]: gatt-time-server: Input/output err
|
||||||
<term><command>kexec</command></term>
|
<term><command>kexec</command></term>
|
||||||
|
|
||||||
<listitem>
|
<listitem>
|
||||||
<para>Shut down and reboot the system via kexec. This is
|
<para>Shut down and reboot the system via <command>kexec</command>. This is equivalent to
|
||||||
mostly equivalent to <command>start kexec.target --job-mode=replace-irreversibly</command>,
|
<command>systemctl start kexec.target --job-mode=replace-irreversibly --no-block</command>. This command is
|
||||||
but also prints a wall message to all users. If combined
|
asynchronous; it will return after the reboot operation is enqueued, without waiting for it to
|
||||||
with <option>--force</option>, shutdown of all running
|
complete.</para>
|
||||||
services is skipped, however all processes are killed and
|
|
||||||
all file systems are unmounted or mounted read-only,
|
<para>If combined with <option>--force</option>, shutdown of all running services is skipped, however all
|
||||||
immediately followed by the reboot.</para>
|
processes are killed and all file systems are unmounted or mounted read-only, immediately followed by the
|
||||||
|
reboot.</para>
|
||||||
</listitem>
|
</listitem>
|
||||||
</varlistentry>
|
</varlistentry>
|
||||||
|
|
||||||
|
|
@ -1787,14 +1790,13 @@ Jan 12 10:46:45 example.com bluetoothd[8900]: gatt-time-server: Input/output err
|
||||||
<term><command>exit <optional><replaceable>EXIT_CODE</replaceable></optional></command></term>
|
<term><command>exit <optional><replaceable>EXIT_CODE</replaceable></optional></command></term>
|
||||||
|
|
||||||
<listitem>
|
<listitem>
|
||||||
<para>Ask the systemd manager to quit. This is only
|
<para>Ask the service manager to quit. This is only supported for user service managers (i.e. in
|
||||||
supported for user service managers (i.e. in conjunction
|
conjunction with the <option>--user</option> option) or in containers and is equivalent to
|
||||||
with the <option>--user</option> option) or in containers
|
<command>poweroff</command> otherwise. This command is asynchronous; it will return after the exit
|
||||||
and is equivalent to <command>poweroff</command> otherwise.</para>
|
operation is enqueued, without waiting for it to complete.</para>
|
||||||
|
|
||||||
<para>The systemd manager can exit with a non-zero exit
|
<para>The service manager will exit with the the specified exit code, if
|
||||||
code if the optional argument
|
<replaceable>EXIT_CODE</replaceable> is passed.</para>
|
||||||
<replaceable>EXIT_CODE</replaceable> is given.</para>
|
|
||||||
</listitem>
|
</listitem>
|
||||||
</varlistentry>
|
</varlistentry>
|
||||||
|
|
||||||
|
|
@ -1818,9 +1820,9 @@ Jan 12 10:46:45 example.com bluetoothd[8900]: gatt-time-server: Input/output err
|
||||||
<term><command>suspend</command></term>
|
<term><command>suspend</command></term>
|
||||||
|
|
||||||
<listitem>
|
<listitem>
|
||||||
<para>Suspend the system. This will trigger activation of
|
<para>Suspend the system. This will trigger activation of the special target unit
|
||||||
the special <filename>suspend.target</filename> target.
|
<filename>suspend.target</filename>. This command is asynchronous, and will return after the suspend
|
||||||
</para>
|
operation is successfully enqueued. It will not wait for the suspend/resume cycle to complete.</para>
|
||||||
</listitem>
|
</listitem>
|
||||||
</varlistentry>
|
</varlistentry>
|
||||||
|
|
||||||
|
|
@ -1828,9 +1830,9 @@ Jan 12 10:46:45 example.com bluetoothd[8900]: gatt-time-server: Input/output err
|
||||||
<term><command>hibernate</command></term>
|
<term><command>hibernate</command></term>
|
||||||
|
|
||||||
<listitem>
|
<listitem>
|
||||||
<para>Hibernate the system. This will trigger activation of
|
<para>Hibernate the system. This will trigger activation of the special target unit
|
||||||
the special <filename>hibernate.target</filename> target.
|
<filename>hibernate.target</filename>. This command is asynchronous, and will return after the hibernation
|
||||||
</para>
|
operation is successfully enqueued. It will not wait for the hibernate/thaw cycle to complete.</para>
|
||||||
</listitem>
|
</listitem>
|
||||||
</varlistentry>
|
</varlistentry>
|
||||||
|
|
||||||
|
|
@ -1838,9 +1840,9 @@ Jan 12 10:46:45 example.com bluetoothd[8900]: gatt-time-server: Input/output err
|
||||||
<term><command>hybrid-sleep</command></term>
|
<term><command>hybrid-sleep</command></term>
|
||||||
|
|
||||||
<listitem>
|
<listitem>
|
||||||
<para>Hibernate and suspend the system. This will trigger
|
<para>Hibernate and suspend the system. This will trigger activation of the special target unit
|
||||||
activation of the special
|
<filename>hybrid-sleep.target</filename>. This command is asynchronous, and will return after the hybrid
|
||||||
<filename>hybrid-sleep.target</filename> target.</para>
|
sleep operation is successfully enqueued. It will not wait for the sleep/wake-up cycle to complete.</para>
|
||||||
</listitem>
|
</listitem>
|
||||||
</varlistentry>
|
</varlistentry>
|
||||||
</variablelist>
|
</variablelist>
|
||||||
|
|
|
||||||
Loading…
Reference in a new issue