git: f9500e75791c - main - shutdown(8): Document additional formats supported by the code.

The branch main has been updated by delphij:

URL: https://cgit.FreeBSD.org/src/commit/?id=f9500e75791cf793904c80ca4a52433afd585a23

commit f9500e75791cf793904c80ca4a52433afd585a23
Author:     Xin LI <delphij@FreeBSD.org>
AuthorDate: 2025-12-09 05:46:24 +0000
Commit:     Xin LI <delphij@FreeBSD.org>
CommitDate: 2025-12-09 05:46:24 +0000

    shutdown(8): Document additional formats supported by the code.
    
    MFC after:      1 week
---
 sbin/shutdown/shutdown.8 | 62 ++++++++++++++++++++++++++++++++++++------------
 1 file changed, 47 insertions(+), 15 deletions(-)

diff --git a/sbin/shutdown/shutdown.8 b/sbin/shutdown/shutdown.8
index ed44ac36aef6..2f09f5d524a9 100644
--- a/sbin/shutdown/shutdown.8
+++ b/sbin/shutdown/shutdown.8
@@ -25,7 +25,7 @@
 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 .\" SUCH DAMAGE.
 .\"
-.Dd August 4, 2024
+.Dd December 8, 2025
 .Dt SHUTDOWN 8
 .Os
 .Sh NAME
@@ -99,10 +99,10 @@ system multi-user with logins disabled (for all but super-user).
 If one of the
 .Fl c ,
 .Fl h ,
-.Fl p
+.Fl p ,
 or
 .Fl r
-options are specified,
+options is specified,
 .Nm
 will execute
 .Xr halt 8
@@ -135,23 +135,42 @@ may be the case-insensitive word
 .Ar now
 (indicating an immediate shutdown) or
 a future time in one of two formats:
-.Ar +number ,
-or
-.Ar yymmddhhmm ,
-where the year, month, and day may be defaulted
-to the current system values.
+.Ar +number
+or an absolute time specification.
 The first form brings the system down in
 .Ar number
-minutes and the second at the absolute time specified.
+time units (defaulting to minutes), and the second at the absolute time specified.
+.Pp
+An absolute time may be specified in one of the following formats,
+where unspecified parts default to the current date:
+.Bl -tag -width "YYMMDDhhmm"
+.It Ar hhmm
+Hour and minute.
+.It Ar DDhhmm
+Day, hour, and minute.
+.It Ar MMDDhhmm
+Month, day, hour, and minute.
+.It Ar YYMMDDhhmm
+Year (within the century), month, day, hour, and minute.
+.El
+.Pp
+The year
+.Ar YY
+is interpreted relative to the current century, with a one-year tolerance
+for values slightly in the past (to accommodate entry at year boundaries).
 .Ar +number
 may be specified in units other than minutes by appending the corresponding
 suffix:
 .Dq Li s ,
 .Dq Li sec ,
+.Dq Li secs ,
 .Dq Li m ,
 .Dq Li min ,
+.Dq Li mins ,
 .Dq Li h ,
-.Dq Li hour .
+.Dq Li hour ,
+.Dq Li hours .
+The unit suffixes are case-insensitive.
 .Pp
 If an absolute time is specified, but not a date,
 and that time today has already passed,
@@ -174,7 +193,7 @@ At intervals, becoming more frequent as apocalypse approaches
 and starting at ten hours before shutdown, warning messages are displayed
 on the terminals of all users logged in.
 Five minutes before
-shutdown, or immediately if shutdown is in less than 5 minutes,
+shutdown, or immediately if shutdown is in less than five minutes,
 logins are disabled by creating
 .Pa /var/run/nologin
 and copying the
@@ -192,7 +211,7 @@ At shutdown time a message is written to the system log, containing the
 time of shutdown, the person who initiated the shutdown and the reason.
 The corresponding signal is then sent to
 .Xr init 8
-to respectively halt, reboot or bring the system down to single-user state
+to respectively halt, reboot, or bring the system down to single-user state
 (depending on the above options).
 The time of the shutdown and the warning message
 are placed in
@@ -220,7 +239,7 @@ exits without executing any action on the system.
 .Pp
 When run without options, the
 .Nm
-utility will place the system into single user mode at the
+utility will place the system into single-user mode at the
 .Ar time
 specified.
 .Pp
@@ -235,7 +254,7 @@ shutdown -p now
 .It Pa /var/run/nologin
 tells
 .Xr login 1
-not to let anyone log in
+not to let anyone log in.
 .It Pa /var/run/noshutdown
 prevents
 .Nm
@@ -249,9 +268,22 @@ Reboot the system in 30 minutes and display a warning message on the terminals
 of all users currently logged in:
 .Pp
 .Dl # shutdown -r +30 \&"System will reboot\&"
+.Pp
+Halt the system at 23:30 (using either format):
+.Pp
+.Dl # shutdown -h 2330
+.Dl # shutdown -h 23:30
+.Pp
+Power off the system on June 15th at 10:00:
+.Pp
+.Dl # shutdown -p 06151000
 .Sh COMPATIBILITY
-The hours and minutes in the second time format may be separated by
+The hours and minutes in any absolute time format may be separated by
 a colon (``:'') for backward compatibility.
+For example,
+.Ar hh:mm
+is accepted as equivalent to
+.Ar hhmm .
 .Sh SEE ALSO
 .Xr kill 1 ,
 .Xr login 1 ,