From: Lennart Poettering Date: Fri, 29 Sep 2017 14:10:27 +0000 (+0200) Subject: man: document which special "systemctl" commands are synchronous and which asynchronous. X-Git-Tag: v235~18^2~1 X-Git-Url: http://review.tizen.org/git/?a=commitdiff_plain;h=6324a8a7271461efb73dc4fe50ad1ebef82e2405;p=platform%2Fupstream%2Fsystemd.git 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 --- diff --git a/man/systemctl.xml b/man/systemctl.xml index f514ab6..4abee60 100644 --- a/man/systemctl.xml +++ b/man/systemctl.xml @@ -407,8 +407,7 @@ - Do not send wall message before halt, power-off, - reboot. + Do not send wall message before halt, power-off and reboot. @@ -525,7 +524,7 @@ twice with any of these operations might result in data loss. Note that when is specified twice the selected operation is executed by systemctl itself, and the system manager is not contacted. This means the command should - succeed even when the system manager hangs or crashed. + succeed even when the system manager has crashed. @@ -533,11 +532,9 @@ - When used with halt, - poweroff, reboot or - kexec, set a short message explaining the reason - for the operation. The message will be logged together with the - default shutdown message. + When used with halt, poweroff or reboot, set a + short message explaining the reason for the operation. The message will be logged together with the default + shutdown message. @@ -1690,8 +1687,8 @@ Jan 12 10:46:45 example.com bluetoothd[8900]: gatt-time-server: Input/output err default - Enter default mode. This is mostly equivalent to - isolate default.target. + Enter default mode. This is equivalent to systemctl isolate default.target. This + operation is blocking by default, use to request asynchronous behavior. @@ -1699,72 +1696,77 @@ Jan 12 10:46:45 example.com bluetoothd[8900]: gatt-time-server: Input/output err rescue - Enter rescue mode. This is mostly equivalent to - isolate rescue.target, but also prints a - wall message to all users. + Enter rescue mode. This is equivalent to systemctl isolate rescue.target. This + operation is blocking by default, use to request asynchronous behavior. emergency - Enter emergency mode. This is mostly equivalent to - isolate emergency.target, but also prints - a wall message to all users. + Enter emergency mode. This is equivalent to systemctl isolate + emergency.target. This operation is blocking by default, use to + request asynchronous behavior. halt - Shut down and halt the system. This is mostly equivalent to start halt.target - --job-mode=replace-irreversibly, but also prints a wall message to all users. If combined with - , 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 system halt. If - 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 - is specified twice the halt operation is executed by - systemctl itself, and the system manager is not contacted. This means the command should - succeed even when the system manager hangs or crashed. + Shut down and halt the system. This is mostly equivalent to systemctl start halt.target + --job-mode=replace-irreversibly --no-block, but also prints a wall message to all users. This command is + asynchronous; it will return after the halt operation is enqueued, without waiting for it to complete. Note + that this operation will simply halt the OS kernel after shutting down, leaving the hardware powered + on. Use systemctl poweroff for powering off the system (see below). + + If combined with , 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 + system halt. If 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 + is specified twice the halt operation is executed by systemctl + itself, and the system manager is not contacted. This means the command should succeed even when the system + manager has crashed. poweroff - Shut down and power-off the system. This is mostly equivalent to start poweroff.target - --job-mode=replace-irreversibly, but also prints a wall message to all users. If combined with - , 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 - 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 + Shut down and power-off the system. This is mostly equivalent to systemctl start + poweroff.target --job-mode=replace-irreversibly --no-block, but also prints a wall message to all + users. This command is asynchronous; it will return after the power-off operation is enqueued, without + waiting for it to complete. + + If combined with , 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 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 is specified twice the power-off operation is executed by systemctl itself, and the system manager is not contacted. This means the command should - succeed even when the system manager hangs or crashed. + succeed even when the system manager has crashed. reboot arg - Shut down and reboot the system. This is mostly equivalent to start reboot.target - --job-mode=replace-irreversibly, but also prints a wall message to all users. If combined with - , 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 - 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 + Shut down and reboot the system. This is mostly equivalent to systemctl start reboot.target + --job-mode=replace-irreversibly --no-block, but also prints a wall message to all users. This + command is asynchronous; it will return after the reboot operation is enqueued, without waiting for it to + complete. + + If combined with , 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 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 is specified twice the reboot operation is executed by systemctl itself, and the system manager is not contacted. This means the command should - succeed even when the system manager hangs or crashed. - - If the optional argument - arg is given, it will be passed - as the optional argument to the - reboot2 - system call. The value is architecture and firmware - specific. As an example, recovery might - be used to trigger system recovery, and - fota might be used to trigger a + succeed even when the system manager has crashed. + + If the optional argument arg is given, it will be passed as the optional + argument to the reboot2 + system call. The value is architecture and firmware specific. As an example, recovery + might be used to trigger system recovery, and fota might be used to trigger a firmware over the air update. @@ -1773,13 +1775,14 @@ Jan 12 10:46:45 example.com bluetoothd[8900]: gatt-time-server: Input/output err kexec - Shut down and reboot the system via kexec. This is - mostly equivalent to start kexec.target --job-mode=replace-irreversibly, - but also prints a wall message to all users. If combined - with , 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. + Shut down and reboot the system via kexec. This is equivalent to + systemctl start kexec.target --job-mode=replace-irreversibly --no-block. This command is + asynchronous; it will return after the reboot operation is enqueued, without waiting for it to + complete. + + If combined with , 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. @@ -1787,14 +1790,13 @@ Jan 12 10:46:45 example.com bluetoothd[8900]: gatt-time-server: Input/output err exit EXIT_CODE - Ask the systemd manager to quit. This is only - supported for user service managers (i.e. in conjunction - with the option) or in containers - and is equivalent to poweroff otherwise. - - The systemd manager can exit with a non-zero exit - code if the optional argument - EXIT_CODE is given. + Ask the service manager to quit. This is only supported for user service managers (i.e. in + conjunction with the option) or in containers and is equivalent to + poweroff otherwise. This command is asynchronous; it will return after the exit + operation is enqueued, without waiting for it to complete. + + The service manager will exit with the the specified exit code, if + EXIT_CODE is passed. @@ -1818,9 +1820,9 @@ Jan 12 10:46:45 example.com bluetoothd[8900]: gatt-time-server: Input/output err suspend - Suspend the system. This will trigger activation of - the special suspend.target target. - + Suspend the system. This will trigger activation of the special target unit + suspend.target. This command is asynchronous, and will return after the suspend + operation is successfully enqueued. It will not wait for the suspend/resume cycle to complete. @@ -1828,9 +1830,9 @@ Jan 12 10:46:45 example.com bluetoothd[8900]: gatt-time-server: Input/output err hibernate - Hibernate the system. This will trigger activation of - the special hibernate.target target. - + Hibernate the system. This will trigger activation of the special target unit + hibernate.target. This command is asynchronous, and will return after the hibernation + operation is successfully enqueued. It will not wait for the hibernate/thaw cycle to complete. @@ -1838,9 +1840,9 @@ Jan 12 10:46:45 example.com bluetoothd[8900]: gatt-time-server: Input/output err hybrid-sleep - Hibernate and suspend the system. This will trigger - activation of the special - hybrid-sleep.target target. + Hibernate and suspend the system. This will trigger activation of the special target unit + hybrid-sleep.target. This command is asynchronous, and will return after the hybrid + sleep operation is successfully enqueued. It will not wait for the sleep/wake-up cycle to complete.