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

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

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>
 

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>