From 1e4acc77b0738b76b982f39eba854e7d81f44b80 Mon Sep 17 00:00:00 2001
From: Yu Watanabe <watanabe.yu+github@gmail.com>
Date: Mon, 30 Apr 2018 22:42:40 +0900
Subject: man: add explanations of show-timesync and timesync-status commands

---
 man/rules/meson.build             |  2 +-
 man/systemd-timesyncd.service.xml |  4 ++
 man/timedatectl.xml               | 92 ++++++++++++++++++++++++++++++++++++++-
 3 files changed, 96 insertions(+), 2 deletions(-)

(limited to 'man')

diff --git a/man/rules/meson.build b/man/rules/meson.build
index b0919b9d44..6b07cfc4fe 100644
--- a/man/rules/meson.build
+++ b/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', [], ''],
diff --git a/man/systemd-timesyncd.service.xml b/man/systemd-timesyncd.service.xml
index 49e00e2b91..b5eb8a4ac2 100644
--- a/man/systemd-timesyncd.service.xml
+++ b/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>
diff --git a/man/timedatectl.xml b/man/timedatectl.xml
index 02b86b6641..b6caa5458d 100644
--- a/man/timedatectl.xml
+++ b/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>
-- 
cgit v1.2.3