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. +