Adding upstream version 247.3.upstream/247.3upstream

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 205 insertions, 0 deletions

diff --git a/man/org.freedesktop.timedate1.xml b/man/org.freedesktop.timedate1.xml
new file mode 100644
index 0000000..52efa68
--- /dev/null
+++ b/man/org.freedesktop.timedate1.xml
@@ -0,0 +1,205 @@
+<?xml version='1.0'?>
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
+  "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" >
+<!-- SPDX-License-Identifier: LGPL-2.1-or-later -->
+
+<refentry id="org.freedesktop.timedate1" conditional='ENABLE_TIMEDATED'
+    xmlns:xi="http://www.w3.org/2001/XInclude">
+  <refentryinfo>
+    <title>org.freedesktop.timedate1</title>
+    <productname>systemd</productname>
+  </refentryinfo>
+
+  <refmeta>
+    <refentrytitle>org.freedesktop.timedate1</refentrytitle>
+    <manvolnum>5</manvolnum>
+  </refmeta>
+
+  <refnamediv>
+    <refname>org.freedesktop.timedate1</refname>
+    <refpurpose>The D-Bus interface of systemd-timedated</refpurpose>
+  </refnamediv>
+
+  <refsect1>
+    <title>Introduction</title>
+
+    <para>
+    <citerefentry><refentrytitle>systemd-timedated.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
+    is a system service that can be used to control the system time and related settings. This page
+    describes the D-Bus interface.</para>
+  </refsect1>
+
+  <refsect1>
+    <title>The D-Bus API</title>
+
+    <para>The service exposes the following interfaces on the bus:</para>
+
+    <programlisting executable="systemd-timedated" node="/org/freedesktop/timedate1" interface="org.freedesktop.timedate1">
+node /org/freedesktop/timedate1 {
+  interface org.freedesktop.timedate1 {
+    methods:
+      SetTime(in  x usec_utc,
+              in  b relative,
+              in  b interactive);
+      SetTimezone(in  s timezone,
+                  in  b interactive);
+      SetLocalRTC(in  b local_rtc,
+                  in  b fix_system,
+                  in  b interactive);
+      SetNTP(in  b use_ntp,
+             in  b interactive);
+      ListTimezones(out as timezones);
+    properties:
+      readonly s Timezone = '...';
+      readonly b LocalRTC = ...;
+      @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
+      readonly b CanNTP = ...;
+      readonly b NTP = ...;
+      @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
+      readonly b NTPSynchronized = ...;
+      @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
+      readonly t TimeUSec = ...;
+      @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
+      readonly t RTCTimeUSec = ...;
+  };
+  interface org.freedesktop.DBus.Peer { ... };
+  interface org.freedesktop.DBus.Introspectable { ... };
+  interface org.freedesktop.DBus.Properties { ... };
+};
+    </programlisting>
+
+    <!--Autogenerated cross-references for systemd.directives, do not edit-->
+
+    <variablelist class="dbus-interface" generated="True" extra-ref="org.freedesktop.timedate1"/>
+
+    <variablelist class="dbus-interface" generated="True" extra-ref="org.freedesktop.timedate1"/>
+
+    <variablelist class="dbus-method" generated="True" extra-ref="SetTime()"/>
+
+    <variablelist class="dbus-method" generated="True" extra-ref="SetTimezone()"/>
+
+    <variablelist class="dbus-method" generated="True" extra-ref="SetLocalRTC()"/>
+
+    <variablelist class="dbus-method" generated="True" extra-ref="SetNTP()"/>
+
+    <variablelist class="dbus-method" generated="True" extra-ref="ListTimezones()"/>
+
+    <variablelist class="dbus-property" generated="True" extra-ref="Timezone"/>
+
+    <variablelist class="dbus-property" generated="True" extra-ref="LocalRTC"/>
+
+    <variablelist class="dbus-property" generated="True" extra-ref="CanNTP"/>
+
+    <variablelist class="dbus-property" generated="True" extra-ref="NTP"/>
+
+    <variablelist class="dbus-property" generated="True" extra-ref="NTPSynchronized"/>
+
+    <variablelist class="dbus-property" generated="True" extra-ref="TimeUSec"/>
+
+    <variablelist class="dbus-property" generated="True" extra-ref="RTCTimeUSec"/>
+
+    <!--End of Autogenerated section-->
+
+    <refsect2>
+      <title>Methods</title>
+
+      <para>Use <function>SetTime()</function> to change the system clock. Pass a value of microseconds since
+      the UNIX epoch (1 Jan 1970 UTC). If <varname>relative</varname> is true, the passed usec value will be
+      added to the current system time. If it is false, the current system time will be set to the passed usec
+      value. If the system time is set with this method, the RTC will be updated as well.</para>
+
+      <para>Use <function>SetTimezone()</function> to set the system timezone. Pass a value like
+      <literal>Europe/Berlin</literal> to set the timezone. Valid timezones are listed in
+      <filename>/usr/share/zoneinfo/zone.tab</filename>. If the RTC is configured to be maintained in local
+      time, it will be updated accordingly.</para>
+
+      <para>Use <function>SetLocalRTC()</function> to control whether the RTC is in local time or UTC. It is
+      strongly recommended to maintain the RTC in UTC. However, some OSes (Windows) maintain the RTC in local
+      time, which might make it necessary to enable this feature. Note that this might create various problems as
+      daylight changes could be missed. If <varname>fix_system</varname> is <literal>true</literal>,
+      the time from the RTC is read again and the system clock is adjusted according to the new setting. If
+      <varname>fix_system</varname> is <literal>false</literal>, the system time is written to the RTC
+      taking the new setting into account. Use <varname>fix_system=true</varname> in installers and livecds
+      where the RTC is probably more reliable than the system time. Use <varname>fix_system=false</varname>
+      in configuration UIs that are run during normal operation and where the system clock is probably more
+      reliable than the RTC.</para>
+
+      <para>Use <function>SetNTP()</function> to control whether the system clock is synchronized with the
+      network using <filename>systemd-timesyncd</filename>. This will enable and start or disable and stop
+      the chosen time synchronization service.</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>interactive</varname> boolean parameters can be used to control whether
+      <ulink url="https://www.freedesktop.org/software/polkit/docs/latest/">polkit</ulink>
+      should interactively ask the user for authentication credentials if required.</para>
+
+      <para>The polkit action for <function>SetTimezone()</function> is
+      <interfacename>org.freedesktop.timedate1.set-timezone</interfacename>. For
+      <function>SetLocalRTC()</function> it is
+      <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>.
+      <function>ListTimezones()</function> does not require any privileges.
+      </para>
+    </refsect2>
+  </refsect1>
+
+  <refsect1>
+    <title>Examples</title>
+
+    <example>
+      <title>Introspect <interfacename>org.freedesktop.timedate1</interfacename> on the bus</title>
+
+      <programlisting>
+$ gdbus introspect --system \
+  --dest org.freedesktop.timedate1 \
+  --object-path /org/freedesktop/timedate1
+      </programlisting>
+    </example>
+  </refsect1>
+
+  <refsect1>
+    <title>Versioning</title>
+
+    <para>These D-Bus interfaces follow <ulink url="http://0pointer.de/blog/projects/versioning-dbus.html">
+    the usual interface versioning guidelines</ulink>.</para>
+  </refsect1>
+
+  <refsect1>
+    <title>See also</title>
+
+      <para><ulink url="https://lists.freedesktop.org/archives/systemd-devel/2011-May/002526.html">More information on how the system clock and RTC interact</ulink></para>
+  </refsect1>
+</refentry>