picnoir
/
Systemd
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

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
This commit is contained in:
Lennart Poettering 2020-08-27 15:45:29 +02:00 committed by Zbigniew Jędrzejewski-Szmek
parent c53aafb7b5
commit 3c719357dc
3 changed files with 27 additions and 9 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

20
man/org.freedesktop.systemd1.xml
View File

@ -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!-->

6
man/systemctl.xml
View File

@ -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>

10
man/systemd.time.xml
View File

@ -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>