man: explain timesyncd epoch mtime touch files in a bit more detail

Let's mention what /usr/lib/clock-epoch precisely does, and underline we
only *advance* the time based on it.

Inspired by Darkdragon-001's #23214.

Replaces #23214

diff --git a/man/systemd-timesyncd.service.xml b/man/systemd-timesyncd.service.xml
index 34e0a674720078d1f5cf132573adee8e34008bda..45fb6b716f1bcc7461348d39505c2f6fcfebf76b 100644 (file)
--- a/man/systemd-timesyncd.service.xml
+++ b/man/systemd-timesyncd.service.xml
@@ -75,14 +75,27 @@
         <term><filename>/var/lib/systemd/timesync/clock</filename></term>
 
         <listitem>
-          <para>The modification time ("mtime") of this file is updated on each successful NTP synchronization
-          or after each <varname>SaveIntervalSec=</varname> time interval, as specified in
-          <citerefentry><refentrytitle>timesyncd.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
-          At the minimum, it will be set to the systemd build date. It is used to ensure that the system clock
-          remains roughly monotonic across reboots, in case no local RTC is available.</para>
+          <para>The modification time ("mtime") of this file is updated on each successful NTP
+          synchronization or after each <varname>SaveIntervalSec=</varname> time interval, as specified in
+          <citerefentry><refentrytitle>timesyncd.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para>
+
+          <para>When initializing, the local clock is advanced to the modification time of this file (if the
+          file timestamp is in the past this adjustment is not made). If the file does not exist yet, the
+          clock is instead advanced to the modification time of <filename>/usr/lib/clock-epoch</filename> –
+          if it exists – or to a time derived from the source tree at build time. This mechanism is used to
+          ensure that the system clock remains somewhat reasonably initialized and roughly monotonic across
+          reboots, in case no battery-buffered local RTC is available.</para>
         </listitem>
       </varlistentry>
 
+      <varlistentry>
+        <term><filename>/usr/lib/clock-epoch</filename></term>
+
+        <listitem><para>The modification time ("mtime") of this file is used for advancing the system clock
+        in case <filename>/var/lib/systemd/timesync/clock</filename> does not exist yet, see
+        above.</para></listitem>
+      </varlistentry>
+
       <varlistentry>
         <term><filename>/run/systemd/timesync/synchronized</filename></term>