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