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 bb1ee0b337d1d75073d168fffc2752465971c053..9362f7d8732f1fc787b8e7e79a36ee844e5919e3 100644 (file)
--- a/man/org.freedesktop.login1.xml
+++ b/man/org.freedesktop.login1.xml
@@ -736,6 +736,12 @@ node /org/freedesktop/login1 {
       <function>CancelScheduledShutdown()</function> cancels a scheduled shutdown. The output parameter
       <varname>cancelled</varname> is true if a shutdown operation was scheduled.</para>
 
+      <para>Note that <varname>usec</varname> 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.</para>
+
       <para><function>SetWallMessage()</function> sets the wall message (the message that will be sent out to
       all terminals and stored in a
       <citerefentry project="man-pages"><refentrytitle>utmp</refentrytitle><manvolnum>5</manvolnum></citerefentry> record) for a

diff --git a/man/shutdown.xml b/man/shutdown.xml
index b92e5836f50df7b0e14b73ef52554f56e4db3a2f..46507f6b84510b6d5d0cf74c1f9e3e754a22a61b 100644 (file)
--- a/man/shutdown.xml
+++ b/man/shutdown.xml
@@ -49,6 +49,13 @@
     for triggering an immediate shutdown. If no time argument is
     specified, <literal>+1</literal> is implied.</para>
 
+    <para>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 <literal>hh:mm</literal> time earlier today) is not an error and
+    results in an immediate shutdown. See the discussion of <option>--when=</option> in
+    <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry> for
+    details.</para>
+
     <para>Note that to specify a wall message you must specify a time
     argument, too.</para>
 

diff --git a/man/systemctl.xml b/man/systemctl.xml
index 8b64b179ea57175a69f925d42e0df4776f431923..e02fd22534dbf7ce3f31b11ef6c159ffa76bceab 100644 (file)
--- 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
           <literal>auto</literal> will schedule the action according to maintenance window or one minute in
           the future.</para>
 
+          <para>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 <emphasis>not</emphasis> 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 <option>--when=now</option>, which by the
+          time the request is processed necessarily refers to the past, or
+          <option>--when=+50ms</option>, 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.</para>
+
+          <para>If a timestamp in the past shall not result in the action being executed, this must be checked
+          for explicitly before invoking <command>systemctl</command>.</para>
+
           <xi:include href="version-info.xml" xpointer="v254"/>
         </listitem>
       </varlistentry>