From: hanjinpeng Date: Sun, 12 Jul 2026 16:52:37 +0000 (-0400) Subject: man: clarify that --when= is a lower bound, not a condition X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=0e7033215d9c450441ecbbbea5d6bec19f850d29;p=thirdparty%2Fsystemd.git man: clarify that --when= is a lower bound, not a condition `systemctl reboot --when=yesterday` reboots the machine immediately, which surprised users enough to be reported as a bug. It is not one: the timestamp passed to --when= (and to ScheduleShutdown(), and to shutdown(8)) declares the earliest point in time the action may be taken, it is not a condition that is evaluated and that could fail. Behaving any differently would be racy and surprising: "--when=now" refers to the past by the time the request is processed, and "--when=+50ms" may well have elapsed already due to scheduling latencies. In both cases we must still carry out the action the user asked for. Document the semantics explicitly in systemctl(1), shutdown(8) and the org.freedesktop.login1(5) D-Bus interface documentation. Fixes: #42437 --- diff --git a/man/org.freedesktop.login1.xml b/man/org.freedesktop.login1.xml index bb1ee0b337d..9362f7d8732 100644 --- a/man/org.freedesktop.login1.xml +++ b/man/org.freedesktop.login1.xml @@ -736,6 +736,12 @@ node /org/freedesktop/login1 { CancelScheduledShutdown() cancels a scheduled shutdown. The output parameter cancelled is true if a shutdown operation was scheduled. + Note that usec is a lower bound only: the shutdown operation is executed as soon + as possible, but not before the specified time. A timestamp in the past is not an error, it simply means + the operation is executed immediately. This is important, since a request to shut down immediately, or a + very short time into the future, typically already refers to the past by the time it is + processed. + SetWallMessage() sets the wall message (the message that will be sent out to all terminals and stored in a utmp5 record) for a diff --git a/man/shutdown.xml b/man/shutdown.xml index b92e5836f50..46507f6b845 100644 --- a/man/shutdown.xml +++ b/man/shutdown.xml @@ -49,6 +49,13 @@ for triggering an immediate shutdown. If no time argument is specified, +1 is implied. + The time string specifies the earliest point in time the shutdown may take place; it is a lower + bound only: the shutdown is executed as soon as possible, but not before the specified time. Specifying a + time that already elapsed (for example an hh:mm time earlier today) is not an error and + results in an immediate shutdown. See the discussion of in + systemctl1 for + details. + Note that to specify a wall message you must specify a time argument, too. diff --git a/man/systemctl.xml b/man/systemctl.xml index 8b64b179ea5..e02fd22534d 100644 --- a/man/systemctl.xml +++ b/man/systemctl.xml @@ -2953,6 +2953,19 @@ Jan 12 10:46:45 example.com bluetoothd[8900]: gatt-time-server: Input/output err auto will schedule the action according to maintenance window or one minute in the future. + The specified timestamp is a lower bound only: it declares the earliest point in time the + requested action may take place, i.e. the action is executed as soon as possible, but not before the + given timestamp. It is not a condition that is checked, and specifying a + timestamp in the past is not an error: the action is then executed immediately. This is intentional, + as the alternative would be racy and surprising — consider , which by the + time the request is processed necessarily refers to the past, or + , which might well already have elapsed due to scheduling latencies + before the request is dispatched. In both cases the requested action is still carried out, as + the user asked for it. + + If a timestamp in the past shall not result in the action being executed, this must be checked + for explicitly before invoking systemctl. +