From: Zbigniew Jędrzejewski-Szmek <zbyszek@in.waw.pl>
Date: Tue, 14 Apr 2020 10:32:53 +0000 (+0200)
Subject: man: timedate1(5) — add missing descriptions
X-Git-Tag: v246-rc1~515^2~3
X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=2a9159244b52b3b0810032b31388ac993a624739;p=thirdparty%2Fsystemd.git

man: timedate1(5) — add missing descriptions
---

diff --git a/man/org.freedesktop.timedate1.xml b/man/org.freedesktop.timedate1.xml
index 000c0ca03e6..73bd9dfedd1 100644
--- a/man/org.freedesktop.timedate1.xml
+++ b/man/org.freedesktop.timedate1.xml
@@ -72,22 +72,6 @@ node /org/freedesktop/timedate1 {
 };
     </programlisting>
 
-    <!--method ListTimezones is not documented!-->
-
-    <!--property Timezone is not documented!-->
-
-    <!--property LocalRTC is not documented!-->
-
-    <!--property CanNTP is not documented!-->
-
-    <!--property NTP is not documented!-->
-
-    <!--property NTPSynchronized is not documented!-->
-
-    <!--property TimeUSec is not documented!-->
-
-    <!--property RTCTimeUSec is not documented!-->
-
     <!--Autogenerated cross-references for systemd.directives, do not edit-->
 
     <variablelist class="dbus-interface" generated="True" extra-ref="org.freedesktop.timedate1"/>
@@ -148,16 +132,39 @@ node /org/freedesktop/timedate1 {
       network using <filename>systemd-timesyncd</filename>. This will enable and start or disable and stop
       the chosen time synchronization service.</para>
 
-      <para>Whenever the timezone and local_rtc settings are changed via the daemon,
-      <function>PropertyChanged</function> signals are sent out to which clients can subscribe. Changing the
-      time settings using this interface is authenticated via PolicyKit.</para>
+      <para><function>ListTimezones()</function> returns a list of time zones known on the local system as an
+      array of names (<literal>["Africa/Abidjan", "Africa/Accra", ..., "UTC"]</literal>).</para>
+    </refsect2>
+
+    <refsect2>
+      <title>Properties</title>
+
+      <para><varname>Timezone</varname> shows the currently configured time zone.
+      <varname>LocalRTC</varname> shows whether the RTC is configured to use UTC (false), or the local time
+      zone (true). <varname>CanNTP</varname> shows whether a service to perform time synchronization over the
+      network is available, and <varname>NTP</varname> shows whether such a service is enabled.</para>
+
+      <para><varname>NTPSynchronized</varname> shows whether the kernel reports the time as synchronized
+      (c.f.
+      <citerefentry project="man-pages"><refentrytitle>adjtimex</refentrytitle><manvolnum>3</manvolnum></citerefentry>).
+      <varname>TimeUSec</varname> and <varname>RTCTimeUSec</varname> show the current time on the system and
+      in the RTC. The purpose of those three properties is to allow remote clients to access this information
+      over D-Bus. Local clients can access the information directly.</para>
+
+      <para>Whenever the <varname>Timezone</varname> and <varname>LocalRTC</varname> settings are changed via
+      the daemon, <function>PropertyChanged</function> signals are sent out to which clients can subscribe.
+      </para>
 
       <para>Note that this service will not inform you about system time changes. Use
       <citerefentry project="man-pages"><refentrytitle>timerfd</refentrytitle><manvolnum>3</manvolnum></citerefentry>
       with <constant>CLOCK_REALTIME</constant> and <constant>TFD_TIMER_CANCEL_ON_SET</constant> for that.
       </para>
+    </refsect2>
+
+    <refsect2>
+      <title>Security</title>
 
-      <para>The <varname>user_interaction</varname> boolean parameters can be used to control whether
+      <para>The <varname>interactive</varname> boolean parameters can be used to control whether
       PolicyKit should interactively ask the user for authentication credentials if required.</para>
 
       <para>The PolicyKit action for <function>SetTimezone()</function> is
@@ -166,7 +173,9 @@ node /org/freedesktop/timedate1 {
       <interfacename>org.freedesktop.timedate1.set-local-rtc</interfacename>, for
       <function>SetTime()</function> it is <interfacename>org.freedesktop.timedate1.set-time</interfacename>
       and for <function>SetNTP()</function> it is
-      <interfacename>org.freedesktop.timedate1.set-ntp</interfacename>.</para>
+      <interfacename>org.freedesktop.timedate1.set-ntp</interfacename>.
+      <function>ListTimezones()</function> does not require any privileges.
+      </para>
     </refsect2>
   </refsect1>