From 3c719357dcd56d4c826ec6a4e6870111c2ee8a36 Mon Sep 17 00:00:00 2001
From: Lennart Poettering <lennart@poettering.net>
Date: Thu, 27 Aug 2020 15:45:29 +0200
Subject: [PATCH] man: extend on the usec/sec discrepancy

Let's document the discrepancy between the Sec and USec suffixing of
unit files and D-Bus properties at three places: in "systemctl show"
(where it already was briefly mentioned), in the D-Bus interface
description (at one place at least, i.e. the most prominent of
properties that encapsulate time values, there are many more) and in the
general man page explaining time values.

By documenting this at all three places I think we now do as much as we
can do about this highlighting the discrepancy of the naming and the
reasons behind it.

Fixes: #2047
---
 man/org.freedesktop.systemd1.xml | 20 ++++++++++++--------
 man/systemctl.xml                |  6 +++++-
 man/systemd.time.xml             | 10 ++++++++++
 3 files changed, 27 insertions(+), 9 deletions(-)

diff --git a/man/org.freedesktop.systemd1.xml b/man/org.freedesktop.systemd1.xml
index 97629c0470..75909aa9e5 100644
--- a/man/org.freedesktop.systemd1.xml
+++ b/man/org.freedesktop.systemd1.xml
@@ -2720,12 +2720,6 @@ node /org/freedesktop/systemd1/unit/avahi_2ddaemon_2eservice {
 
     <!--property RestartUSec is not documented!-->
 
-    <!--property TimeoutStartUSec is not documented!-->
-
-    <!--property TimeoutStopUSec is not documented!-->
-
-    <!--property TimeoutAbortUSec is not documented!-->
-
     <!--property TimeoutStartFailureMode is not documented!-->
 
     <!--property TimeoutStopFailureMode is not documented!-->
@@ -3772,6 +3766,18 @@ node /org/freedesktop/systemd1/unit/avahi_2ddaemon_2eservice {
       <para>Most properties of the Service interface map directly to the corresponding settings in service
       unit files. For the sake of brevity, here's a list of all exceptions only:</para>
 
+      <para><varname>TimeoutStartUSec</varname>, <varname>TimeoutStopUSec</varname> and
+      <varname>TimeoutAbortUSec</varname> contain the start, stop and abort timeouts, in microseconds. Note
+      the slight difference in naming when compared to the matching unit file settings (see
+      <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>7</manvolnum></citerefentry>):
+      these bus properties strictly use microseconds (and thus are suffixed <varname>…USec</varname>) while
+      the unit file settings default to a time unit of seconds (and thus are suffixed
+      <varname>…Sec</varname>), unless a different unit is explicitly specified. This reflects that fact that
+      internally the service manager deals in microsecond units only, and the bus properties are a relatively
+      low-level (binary) concept exposing this. The unit file settings on the other hand are relatively
+      high-level (string-based) concepts and thus support more user friendly time specifications which
+      default to second time units but allow other units too, if specified.</para>
+
       <para><varname>WatchdogTimestamp</varname> and <varname>WatchdogTimestampMonotonic</varname> contain
       <constant>CLOCK_REALTIME</constant>/<constant>CLOCK_MONOTONIC</constant> microsecond timestamps of the
       last watchdog ping received from the service, or 0 if none was ever received.</para>
@@ -9238,8 +9244,6 @@ node /org/freedesktop/systemd1/unit/session_2d1_2escope {
 
     <!--method AttachProcesses is not documented!-->
 
-    <!--property TimeoutStopUSec is not documented!-->
-
     <!--property RuntimeMaxUSec is not documented!-->
 
     <!--property Slice is not documented!-->
diff --git a/man/systemctl.xml b/man/systemctl.xml
index bb3a296645..1c55028837 100644
--- a/man/systemctl.xml
+++ b/man/systemctl.xml
@@ -446,7 +446,11 @@ Jan 12 10:46:45 example.com bluetoothd[8900]: gatt-time-server: Input/output err
             current main process identifier as <literal>MainPID</literal> (which is runtime state), and time settings
             are always exposed as properties ending in the <literal>…USec</literal> suffix even if a matching
             configuration options end in <literal>…Sec</literal>, because microseconds is the normalized time unit used
-            by the system and service manager.</para>
+            internally by the system and service manager.</para>
+
+            <para>For details about many of these properties, see the documentation of the D-Bus interface
+            backing these properties, see
+            <citerefentry><refentrytitle>org.freedesktop.systemd1</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para>
           </listitem>
         </varlistentry>
         <varlistentry>
diff --git a/man/systemd.time.xml b/man/systemd.time.xml
index 5b7800e78b..79fe9735c4 100644
--- a/man/systemd.time.xml
+++ b/man/systemd.time.xml
@@ -75,6 +75,16 @@
     <para>One can use the <command>timespan</command> command of
     <citerefentry><refentrytitle>systemd-analyze</refentrytitle><manvolnum>1</manvolnum></citerefentry>
     to normalise a textual time span for testing and validation purposes.</para>
+
+    <para>Internally, systemd generally operates with microsecond time granularity, while the default time
+    unit in user-configurable time spans is usually seconds (see above). This disparity becomes visible when
+    comparing the same settings in the (high-level) unit file syntax with the matching (more low-level) D-Bus
+    properties (which are what
+    <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>'s
+    <command>show</command> command displays). The former typically are suffixed with <literal>…Sec</literal>
+    to indicate the default unit of seconds, the latter are typically suffixed with <literal>…USec</literal>
+    to indicate the underlying low-level time unit, even if they both encapsulate the very same
+    settings.</para>
   </refsect1>
 
   <refsect1>