man: add explanations of show-timesync and timesync-status commands

man/rules/meson.build

@@ -706,7 +706,7 @@ manpages = [
  ['systemd.unit', '5', [], ''],
  ['sysusers.d', '5', [], 'ENABLE_SYSUSERS'],
  ['telinit', '8', [], ''],
- ['timedatectl', '1', [], 'ENABLE_TIMEDATED'],
+ ['timedatectl', '1', [], 'ENABLE_TIMEDATECTL'],
  ['timesyncd.conf', '5', ['timesyncd.conf.d'], 'ENABLE_TIMESYNCD'],
  ['tmpfiles.d', '5', [], ''],
  ['udev', '7', [], ''],

man/systemd-timesyncd.service.xml

@@ -70,6 +70,10 @@
     <para><citerefentry><refentrytitle>timedatectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>'s
     <command>set-ntp</command> command may be used to enable and
     start, or disable and stop this service.</para>
+
+    <para><citerefentry><refentrytitle>timedatectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>'s
+    <command>timesync-status</command> or <command>show-timesync</command> command can be used to show the
+    current status of this service.</para>
   </refsect1>
 
   <refsect1>

man/timedatectl.xml

@@ -10,7 +10,7 @@
   Copyright 2012 Lennart Poettering
 -->
 
-<refentry id="timedatectl" conditional='ENABLE_TIMEDATED'
+<refentry id="timedatectl" conditional='ENABLE_TIMEDATECTL'
   xmlns:xi="http://www.w3.org/2001/XInclude">
 
   <refentryinfo>
@@ -53,6 +53,11 @@
     <citerefentry><refentrytitle>systemd-firstboot</refentrytitle><manvolnum>1</manvolnum></citerefentry>
     to initialize the system time zone for mounted (but not booted)
     system images.</para>
+
+    <para><command>timedatectl</command> may be used to show the current status of
+    <citerefentry><refentrytitle>systemd-timesyncd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>.
+    </para>
+
   </refsect1>
 
   <refsect1>
@@ -78,6 +83,43 @@
         clock.</para></listitem>
       </varlistentry>
 
+      <varlistentry>
+        <term><option>--monitor</option></term>
+
+        <listitem><para>If <command>timesync-status</command> is invoked and this option is passed,
+        then <command>timedatectl</command> monitors the status of
+        <citerefentry><refentrytitle>systemd-timesyncd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
+        and updates the outputs. Use Ctrl-C to terminate the monitoring.</para></listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><option>-a</option></term>
+        <term><option>-all</option></term>
+
+        <listitem><para>When showing properties of
+        <citerefentry><refentrytitle>systemd-timesyncd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
+        show all properties regardless of whether they are set or not.</para></listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><option>-p</option></term>
+        <term><option>--property=</option></term>
+
+        <listitem><para>When showing properties of
+        <citerefentry><refentrytitle>systemd-timesyncd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
+        limit display to certain properties as specified as argument. If not specified, all set properties are shown.
+        The argument should be a property name, such as <literal>ServerName</literal>. If specified more than once,
+        all properties with the specified names are shown.</para></listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><option>--value</option></term>
+
+        <listitem>
+          <para>When printing properties with <command>show-timesync</command>, only print the value, and skip the
+          property name and <literal>=</literal>.</para></listitem>
+      </varlistentry>
+
       <xi:include href="user-system-options.xml" xpointer="host" />
       <xi:include href="user-system-options.xml" xpointer="machine" />
 
@@ -165,6 +207,35 @@
 
     </variablelist>
 
+    <refsect2><title>systemd-timesyncd Commands</title>
+
+    <para>The following commands are specific to
+    <citerefentry><refentrytitle>systemd-timesyncd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>.
+    </para>
+
+      <variablelist>
+        <varlistentry>
+          <term><command>timesync-status</command></term>
+
+          <listitem><para>Show current status of
+          <citerefentry><refentrytitle>systemd-timesyncd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>.
+          If <option>--monitor</option> is specified, then this will monitor the status updates.</para></listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term><command>show-timesync</command></term>
+
+          <listitem><para>Show properties of the manager of
+          <citerefentry><refentrytitle>systemd-timesyncd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>.
+          By default, empty properties are suppressed. Use <option>--all</option> to show those too. To select specific
+          properties to show, use <option>--property=</option>. This command is intended to be used whenever
+          computer-parsable output is required. Use <option>timesync-status</option> if you are looking for formatted
+          human-readable output.</para></listitem>
+        </varlistentry>
+      </variablelist>
+
+    </refsect2>
+
   </refsect1>
 
   <refsect1>
@@ -208,6 +279,25 @@ Password: ********
            └─595 /usr/lib/systemd/systemd-timesyncd
 …</programlisting>
     </para>
+
+    <para>Show current status of
+    <citerefentry><refentrytitle>systemd-timesyncd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>:
+    <programlisting>$ timedatectl timesync-status
+       Server: 216.239.38.15 (time4.google.com)
+Poll interval: 1min 4s (min: 32s; max 34min 8s)
+         Leap: normal
+      Version: 4
+      Stratum: 1
+    Reference: GPS
+    Precision: 1us (-20)
+Root distance: 335us (max: 5s)
+       Offset: +316us
+        Delay: 349us
+       Jitter: 0
+ Packet count: 1
+    Frequency: -8.802ppm</programlisting>
+    </para>
+
   </refsect1>
 
   <refsect1>