206 lines
9.2 KiB
XML
206 lines
9.2 KiB
XML
<?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>
|