From: Zbigniew Jędrzejewski-Szmek Date: Tue, 6 Dec 2022 10:27:31 +0000 (+0100) Subject: man: deemphasize "halt" X-Git-Tag: v253-rc1~345^2 X-Git-Url: http://git-history.diyao.me/?a=commitdiff_plain;h=269d17f9559a08b9801bd25d01840ce6ee42fc7f;p=systemd%2F.git man: deemphasize "halt" Systemd documents "halt" as the primary shutdown mechanism, redirecting "reboot" and "shutdown" to the halt(8), but halt is a really strange and obsolete concept. Who would want to really keep their machine running after shutdown? I expect that halting is almost unused. Let's at least make it less prominent in the docs. While at it, use "power off" for a verb and "power-off" for noun (but "poweroff" of the actual command name). --- diff --git a/man/halt.xml b/man/halt.xml deleted file mode 100644 index c13ee5c144..0000000000 --- a/man/halt.xml +++ /dev/null @@ -1,160 +0,0 @@ - - - - - - - - halt - systemd - - - - halt - 8 - - - - halt - poweroff - reboot - Halt, power-off or reboot the machine - - - - - halt - OPTIONS - - - poweroff - OPTIONS - - - reboot - OPTIONS - - - - - Description - - halt, poweroff, reboot may be used to - halt, power-off, or reboot the machine. All three commands take the same options. - - - - - Options - - The following options are understood: - - - - - - - - - - - - Halt the machine, regardless of which one of - the three commands is invoked. - - - - - - - Power-off the machine, when either halt - or poweroff is invoked. This option is ignored when - reboot is invoked. - - - - - - Reboot the machine, regardless of which one of - the three commands is invoked. - - - - - - - - Force immediate halt, power-off, reboot. If specified, the command does not contact the init - system. In most cases, filesystems are not properly unmounted before shutdown. For example, the - command reboot -f is mostly equivalent to systemctl reboot -ff, - instead of systemctl reboot -f. - - - - - - - - Only write wtmp shutdown entry, do not - actually halt, power-off, reboot. - - - - - - - Do not write wtmp shutdown - entry. - - - - - - - Don't sync hard disks/storage media before - halt, power-off, reboot. - - - - - - Do not send wall message before halt, - power-off, reboot. - - - - - - Exit status - - On success, 0 is returned, a non-zero failure code - otherwise. - - - - Notes - - These commands are implemented in a way that preserves basic compatibility with the original SysV - commands. systemctl1 - verbs halt, poweroff, reboot provide the same - functionality with some additional features. - - Note that on many SysV systems halt used to be synonymous to - poweroff, i.e. both commands would equally result in powering the machine off. systemd - is more accurate here, and halt results in halting the machine only (leaving power - on), and poweroff is required to actually power it off. - - - - See Also - - systemd1, - systemctl1, - shutdown8, - wall1 - - - - diff --git a/man/poweroff.xml b/man/poweroff.xml new file mode 100644 index 0000000000..2841dc7769 --- /dev/null +++ b/man/poweroff.xml @@ -0,0 +1,158 @@ + + + + + + + + poweroff + systemd + + + + poweroff + 8 + + + + poweroff + reboot + halt + Power off, reboot, or halt the machine + + + + + poweroff + OPTIONS + + + reboot + OPTIONS + + + halt + OPTIONS + + + + + Description + + poweroff, reboot, and halt may be used to + power off, reboot, or halt the machine. All three commands take the same options. + + + + + Options + + The following options are understood: + + + + + + + + + + + + Halt the machine, regardless of which one of + the three commands is invoked. + + + + + + + Power off the machine, when either halt + or poweroff is invoked. This option is ignored when + reboot is invoked. + + + + + + Reboot the machine, regardless of which one of + the three commands is invoked. + + + + + + + + Force immediate power-off, halt, or reboot. If specified, the command does not contact the + init system. In most cases, filesystems are not properly unmounted before shutdown. For example, + the command reboot -f is mostly equivalent to + systemctl reboot -ff, instead of systemctl reboot -f. + + + + + + + + + Only write wtmp shutdown entry, do not actually power off, reboot, or halt. + + + + + + + + Do not write wtmp shutdown entry. + + + + + + + Don't sync hard disks/storage media before power-off, reboot, or halt. + + + + + + + Do not send wall message before power-off, reboot, or halt. + + + + + + Exit status + + On success, 0 is returned, a non-zero failure code otherwise. + + + + Notes + + These commands are implemented in a way that preserves basic compatibility with the original SysV + commands. systemctl1 + verbs poweroff, reboot, halt provide the same + functionality with some additional features. + + Note that on many SysV systems halt used to be synonymous to + poweroff, i.e. both commands would equally result in powering the machine off. systemd + is more accurate here, and halt results in halting the machine only (leaving power + on), and poweroff is required to actually power it off. + + + + See Also + + systemd1, + systemctl1, + shutdown8, + wall1 + + + + diff --git a/man/rules/meson.build b/man/rules/meson.build index ac4196e548..4c79c77e67 100644 --- a/man/rules/meson.build +++ b/man/rules/meson.build @@ -18,7 +18,6 @@ manpages = [ 'ENABLE_RESOLVE'], ['environment.d', '5', [], 'ENABLE_ENVIRONMENT_D'], ['file-hierarchy', '7', [], ''], - ['halt', '8', ['poweroff', 'reboot'], ''], ['homectl', '1', [], 'ENABLE_HOMED'], ['homed.conf', '5', ['homed.conf.d'], 'ENABLE_HOMED'], ['hostname', '5', [], ''], @@ -67,6 +66,7 @@ manpages = [ ['pam_systemd', '8', [], 'HAVE_PAM'], ['pam_systemd_home', '8', [], 'ENABLE_PAM_HOME'], ['portablectl', '1', [], 'ENABLE_PORTABLED'], + ['poweroff', '8', ['halt', 'reboot'], ''], ['pstore.conf', '5', ['pstore.conf.d'], 'ENABLE_PSTORE'], ['repart.d', '5', [], 'ENABLE_REPART'], ['resolvectl', '1', ['resolvconf'], 'ENABLE_RESOLVE'], @@ -897,13 +897,6 @@ manpages = [ ['systemd-fstab-generator', '8', [], ''], ['systemd-getty-generator', '8', [], ''], ['systemd-gpt-auto-generator', '8', [], 'HAVE_BLKID'], - ['systemd-halt.service', - '8', - ['systemd-kexec.service', - 'systemd-poweroff.service', - 'systemd-reboot.service', - 'systemd-shutdown'], - ''], ['systemd-hibernate-resume-generator', '8', [], 'ENABLE_HIBERNATE'], ['systemd-hibernate-resume@.service', '8', @@ -978,6 +971,13 @@ manpages = [ 'systemd-pcrphase-sysinit.service'], 'HAVE_GNU_EFI'], ['systemd-portabled.service', '8', ['systemd-portabled'], 'ENABLE_PORTABLED'], + ['systemd-poweroff.service', + '8', + ['systemd-halt.service', + 'systemd-kexec.service', + 'systemd-reboot.service', + 'systemd-shutdown'], + ''], ['systemd-pstore.service', '8', ['systemd-pstore'], 'ENABLE_PSTORE'], ['systemd-quotacheck.service', '8', diff --git a/man/systemd-halt.service.xml b/man/systemd-halt.service.xml deleted file mode 100644 index 0378418192..0000000000 --- a/man/systemd-halt.service.xml +++ /dev/null @@ -1,92 +0,0 @@ - - - - - - - - systemd-halt.service - systemd - - - - systemd-halt.service - 8 - - - - systemd-halt.service - systemd-poweroff.service - systemd-reboot.service - systemd-kexec.service - systemd-shutdown - System shutdown logic - - - - systemd-halt.service - systemd-poweroff.service - systemd-reboot.service - systemd-kexec.service - /usr/lib/systemd/systemd-shutdown - /usr/lib/systemd/system-shutdown/ - - - - Description - - systemd-halt.service is a system - service that is pulled in by halt.target and - is responsible for the actual system halt. Similarly, - systemd-poweroff.service is pulled in by - poweroff.target, - systemd-reboot.service by - reboot.target and - systemd-kexec.service by - kexec.target to execute the respective - actions. - - When these services are run, they ensure that PID 1 is - replaced by the - /usr/lib/systemd/systemd-shutdown tool which - is then responsible for the actual shutdown. Before shutting down, - this binary will try to unmount all remaining file systems, - disable all remaining swap devices, detach all remaining storage - devices and kill all remaining processes. - - It is necessary to have this code in a separate binary - because otherwise rebooting after an upgrade might be broken — the - running PID 1 could still depend on libraries which are not - available any more, thus keeping the file system busy, which then - cannot be re-mounted read-only. - - Immediately before executing the actual system - halt/poweroff/reboot/kexec systemd-shutdown - will run all executables in - /usr/lib/systemd/system-shutdown/ and pass - one arguments to them: either halt, - poweroff, reboot or - kexec, depending on the chosen action. All - executables in this directory are executed in parallel, and - execution of the action is not continued before all executables - finished. - - Note that systemd-halt.service (and the related units) should never be - executed directly. Instead, trigger system shutdown with a command such as systemctl - halt. - - - - See Also - - systemd1, - systemctl1, - systemd.special7, - reboot2, - systemd-suspend.service8, - bootup7 - - - - diff --git a/man/systemd-poweroff.service.xml b/man/systemd-poweroff.service.xml new file mode 100644 index 0000000000..9adfcc5af0 --- /dev/null +++ b/man/systemd-poweroff.service.xml @@ -0,0 +1,92 @@ + + + + + + + + systemd-poweroff.service + systemd + + + + systemd-poweroff.service + 8 + + + + systemd-poweroff.service + systemd-halt.service + systemd-reboot.service + systemd-kexec.service + systemd-shutdown + System shutdown logic + + + + systemd-poweroff.service + systemd-halt.service + systemd-reboot.service + systemd-kexec.service + /usr/lib/systemd/systemd-shutdown + /usr/lib/systemd/system-shutdown/ + + + + Description + + systemd-poweroff.service is a system + service that is pulled in by poweroff.target and + is responsible for the actual system power-off operation. Similarly, + systemd-halt.service is pulled in by + halt.target, + systemd-reboot.service by + reboot.target and + systemd-kexec.service by + kexec.target to execute the respective + actions. + + When these services are run, they ensure that PID 1 is + replaced by the + /usr/lib/systemd/systemd-shutdown tool which + is then responsible for the actual shutdown. Before shutting down, + this binary will try to unmount all remaining file systems, + disable all remaining swap devices, detach all remaining storage + devices and kill all remaining processes. + + It is necessary to have this code in a separate binary + because otherwise rebooting after an upgrade might be broken — the + running PID 1 could still depend on libraries which are not + available any more, thus keeping the file system busy, which then + cannot be re-mounted read-only. + + Immediately before executing the actual system + power-off/halt/reboot/kexec systemd-shutdown + will run all executables in + /usr/lib/systemd/system-shutdown/ and pass + one arguments to them: either poweroff, + halt, reboot, or + kexec, depending on the chosen action. All + executables in this directory are executed in parallel, and + execution of the action is not continued before all executables + finished. + + Note that systemd-poweroff.service (and the related units) should never be + executed directly. Instead, trigger system shutdown with a command such as systemctl + poweroff. + + + + See Also + + systemd1, + systemctl1, + systemd.special7, + reboot2, + systemd-suspend.service8, + bootup7 + + + +