diff options
Diffstat (limited to 'man/org.freedesktop.timedate1.xml')
| -rw-r--r-- | man/org.freedesktop.timedate1.xml | 200 |
1 files changed, 200 insertions, 0 deletions
diff --git a/man/org.freedesktop.timedate1.xml b/man/org.freedesktop.timedate1.xml new file mode 100644 index 0000000..54f4018 --- /dev/null +++ b/man/org.freedesktop.timedate1.xml @@ -0,0 +1,200 @@ +<?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> + + <xi:include href="org.freedesktop.locale1.xml" xpointer="versioning"/> + + <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> |