]>
Commit | Line | Data |
---|---|---|
9c970e5f ZJS |
1 | <?xml version='1.0'?> |
2 | <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" | |
3 | "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" > | |
4 | <!-- SPDX-License-Identifier: LGPL-2.1+ --> | |
5 | ||
6 | <refentry id="org.freedesktop.timedate1" conditional='ENABLE_TIMEDATED' | |
7 | xmlns:xi="http://www.w3.org/2001/XInclude"> | |
8 | <refentryinfo> | |
9 | <title>org.freedesktop.timedate1</title> | |
10 | <productname>systemd</productname> | |
11 | </refentryinfo> | |
12 | ||
13 | <refmeta> | |
14 | <refentrytitle>org.freedesktop.timedate1</refentrytitle> | |
15 | <manvolnum>5</manvolnum> | |
16 | </refmeta> | |
17 | ||
18 | <refnamediv> | |
19 | <refname>org.freedesktop.timedate1</refname> | |
20 | <refpurpose>The D-Bus interface of systemd-timedated</refpurpose> | |
21 | </refnamediv> | |
22 | ||
23 | <refsect1> | |
24 | <title>Introduction</title> | |
25 | ||
26 | <para> | |
27 | <citerefentry><refentrytitle>systemd-timedated.service</refentrytitle><manvolnum>8</manvolnum></citerefentry> | |
ca264f7d | 28 | is a system service that can be used to control the system time and related settings. This page |
9c970e5f ZJS |
29 | describes the D-Bus interface.</para> |
30 | </refsect1> | |
31 | ||
32 | <refsect1> | |
33 | <title>The D-Bus API</title> | |
34 | ||
35 | <para>The service exposes the following interfaces on the bus:</para> | |
36 | ||
48f99d7c | 37 | <programlisting executable="systemd-timedated" node="/org/freedesktop/timedate1" interface="org.freedesktop.timedate1"> |
9c970e5f ZJS |
38 | node /org/freedesktop/timedate1 { |
39 | interface org.freedesktop.timedate1 { | |
40 | methods: | |
41 | SetTime(in x usec_utc, | |
42 | in b relative, | |
4fb222c4 | 43 | in b interactive); |
9c970e5f | 44 | SetTimezone(in s timezone, |
4fb222c4 | 45 | in b interactive); |
9c970e5f ZJS |
46 | SetLocalRTC(in b local_rtc, |
47 | in b fix_system, | |
4fb222c4 | 48 | in b interactive); |
9c970e5f | 49 | SetNTP(in b use_ntp, |
4fb222c4 ZJS |
50 | in b interactive); |
51 | ListTimezones(out as timezones); | |
9c970e5f | 52 | properties: |
4fb222c4 ZJS |
53 | readonly s Timezone = '...'; |
54 | readonly b LocalRTC = ...; | |
55 | @org.freedesktop.DBus.Property.EmitsChangedSignal("false") | |
56 | readonly b CanNTP = ...; | |
57 | readonly b NTP = ...; | |
58 | @org.freedesktop.DBus.Property.EmitsChangedSignal("false") | |
59 | readonly b NTPSynchronized = ...; | |
60 | @org.freedesktop.DBus.Property.EmitsChangedSignal("false") | |
61 | readonly t TimeUSec = ...; | |
62 | @org.freedesktop.DBus.Property.EmitsChangedSignal("false") | |
63 | readonly t RTCTimeUSec = ...; | |
9c970e5f | 64 | }; |
4fb222c4 ZJS |
65 | interface org.freedesktop.DBus.Peer { ... }; |
66 | interface org.freedesktop.DBus.Introspectable { ... }; | |
67 | interface org.freedesktop.DBus.Properties { ... }; | |
9c970e5f ZJS |
68 | }; |
69 | </programlisting> | |
70 | ||
00bb75d7 ZJS |
71 | <!--Autogenerated cross-references for systemd.directives, do not edit--> |
72 | ||
73 | <variablelist class="dbus-interface" generated="True" extra-ref="org.freedesktop.timedate1"/> | |
74 | ||
75 | <variablelist class="dbus-interface" generated="True" extra-ref="org.freedesktop.timedate1"/> | |
76 | ||
77 | <variablelist class="dbus-method" generated="True" extra-ref="SetTime()"/> | |
78 | ||
79 | <variablelist class="dbus-method" generated="True" extra-ref="SetTimezone()"/> | |
80 | ||
81 | <variablelist class="dbus-method" generated="True" extra-ref="SetLocalRTC()"/> | |
82 | ||
83 | <variablelist class="dbus-method" generated="True" extra-ref="SetNTP()"/> | |
84 | ||
85 | <variablelist class="dbus-method" generated="True" extra-ref="ListTimezones()"/> | |
86 | ||
87 | <variablelist class="dbus-property" generated="True" extra-ref="Timezone"/> | |
88 | ||
89 | <variablelist class="dbus-property" generated="True" extra-ref="LocalRTC"/> | |
90 | ||
91 | <variablelist class="dbus-property" generated="True" extra-ref="CanNTP"/> | |
92 | ||
93 | <variablelist class="dbus-property" generated="True" extra-ref="NTP"/> | |
94 | ||
95 | <variablelist class="dbus-property" generated="True" extra-ref="NTPSynchronized"/> | |
96 | ||
97 | <variablelist class="dbus-property" generated="True" extra-ref="TimeUSec"/> | |
98 | ||
99 | <variablelist class="dbus-property" generated="True" extra-ref="RTCTimeUSec"/> | |
100 | ||
101 | <!--End of Autogenerated section--> | |
102 | ||
9c970e5f ZJS |
103 | <refsect2> |
104 | <title>Methods</title> | |
105 | ||
106 | <para>Use <function>SetTime()</function> to change the system clock. Pass a value of microseconds since | |
107 | the UNIX epoch (1 Jan 1970 UTC). If <varname>relative</varname> is true, the passed usec value will be | |
ca264f7d DDM |
108 | added to the current system time. If it is false, the current system time will be set to the passed usec |
109 | value. If the system time is set with this method, the RTC will be updated as well.</para> | |
9c970e5f ZJS |
110 | |
111 | <para>Use <function>SetTimezone()</function> to set the system timezone. Pass a value like | |
112 | <literal>Europe/Berlin</literal> to set the timezone. Valid timezones are listed in | |
113 | <filename>/usr/share/zoneinfo/zone.tab</filename>. If the RTC is configured to be maintained in local | |
114 | time, it will be updated accordingly.</para> | |
115 | ||
116 | <para>Use <function>SetLocalRTC()</function> to control whether the RTC is in local time or UTC. It is | |
ca264f7d DDM |
117 | strongly recommended to maintain the RTC in UTC. However, some OSes (Windows) maintain the RTC in local |
118 | time, which might make it necessary to enable this feature. Note that this might create various problems as | |
119 | daylight changes could be missed. If <varname>fix_system</varname> is <literal>true</literal>, | |
120 | the time from the RTC is read again and the system clock is adjusted according to the new setting. If | |
121 | <varname>fix_system</varname> is <literal>false</literal>, the system time is written to the RTC | |
9c970e5f ZJS |
122 | taking the new setting into account. Use <varname>fix_system=true</varname> in installers and livecds |
123 | where the RTC is probably more reliable than the system time. Use <varname>fix_system=false</varname> | |
124 | in configuration UIs that are run during normal operation and where the system clock is probably more | |
125 | reliable than the RTC.</para> | |
126 | ||
127 | <para>Use <function>SetNTP()</function> to control whether the system clock is synchronized with the | |
128 | network using <filename>systemd-timesyncd</filename>. This will enable and start or disable and stop | |
129 | the chosen time synchronization service.</para> | |
130 | ||
2a915924 ZJS |
131 | <para><function>ListTimezones()</function> returns a list of time zones known on the local system as an |
132 | array of names (<literal>["Africa/Abidjan", "Africa/Accra", ..., "UTC"]</literal>).</para> | |
133 | </refsect2> | |
134 | ||
135 | <refsect2> | |
136 | <title>Properties</title> | |
137 | ||
138 | <para><varname>Timezone</varname> shows the currently configured time zone. | |
139 | <varname>LocalRTC</varname> shows whether the RTC is configured to use UTC (false), or the local time | |
140 | zone (true). <varname>CanNTP</varname> shows whether a service to perform time synchronization over the | |
141 | network is available, and <varname>NTP</varname> shows whether such a service is enabled.</para> | |
142 | ||
143 | <para><varname>NTPSynchronized</varname> shows whether the kernel reports the time as synchronized | |
144 | (c.f. | |
145 | <citerefentry project="man-pages"><refentrytitle>adjtimex</refentrytitle><manvolnum>3</manvolnum></citerefentry>). | |
146 | <varname>TimeUSec</varname> and <varname>RTCTimeUSec</varname> show the current time on the system and | |
147 | in the RTC. The purpose of those three properties is to allow remote clients to access this information | |
148 | over D-Bus. Local clients can access the information directly.</para> | |
149 | ||
150 | <para>Whenever the <varname>Timezone</varname> and <varname>LocalRTC</varname> settings are changed via | |
151 | the daemon, <function>PropertyChanged</function> signals are sent out to which clients can subscribe. | |
152 | </para> | |
9c970e5f ZJS |
153 | |
154 | <para>Note that this service will not inform you about system time changes. Use | |
4fb222c4 | 155 | <citerefentry project="man-pages"><refentrytitle>timerfd</refentrytitle><manvolnum>3</manvolnum></citerefentry> |
9c970e5f ZJS |
156 | with <constant>CLOCK_REALTIME</constant> and <constant>TFD_TIMER_CANCEL_ON_SET</constant> for that. |
157 | </para> | |
2a915924 ZJS |
158 | </refsect2> |
159 | ||
160 | <refsect2> | |
161 | <title>Security</title> | |
9c970e5f | 162 | |
2a915924 | 163 | <para>The <varname>interactive</varname> boolean parameters can be used to control whether |
98ab0dae ZJS |
164 | <ulink url="https://www.freedesktop.org/software/polkit/docs/latest/">polkit</ulink> |
165 | should interactively ask the user for authentication credentials if required.</para> | |
9c970e5f | 166 | |
98ab0dae | 167 | <para>The polkit action for <function>SetTimezone()</function> is |
9c970e5f ZJS |
168 | <interfacename>org.freedesktop.timedate1.set-timezone</interfacename>. For |
169 | <function>SetLocalRTC()</function> it is | |
170 | <interfacename>org.freedesktop.timedate1.set-local-rtc</interfacename>, for | |
171 | <function>SetTime()</function> it is <interfacename>org.freedesktop.timedate1.set-time</interfacename> | |
172 | and for <function>SetNTP()</function> it is | |
2a915924 ZJS |
173 | <interfacename>org.freedesktop.timedate1.set-ntp</interfacename>. |
174 | <function>ListTimezones()</function> does not require any privileges. | |
175 | </para> | |
9c970e5f ZJS |
176 | </refsect2> |
177 | </refsect1> | |
178 | ||
48f99d7c ZJS |
179 | <refsect1> |
180 | <title>Examples</title> | |
181 | ||
182 | <example> | |
183 | <title>Introspect <interfacename>org.freedesktop.timedate1</interfacename> on the bus</title> | |
184 | ||
185 | <programlisting> | |
186 | $ gdbus introspect --system \ | |
187 | --dest org.freedesktop.timedate1 \ | |
188 | --object-path /org/freedesktop/timedate1 | |
189 | </programlisting> | |
190 | </example> | |
191 | </refsect1> | |
192 | ||
9c970e5f ZJS |
193 | <refsect1> |
194 | <title>Versioning</title> | |
195 | ||
196 | <para>These D-Bus interfaces follow <ulink url="http://0pointer.de/blog/projects/versioning-dbus.html"> | |
197 | the usual interface versioning guidelines</ulink>.</para> | |
198 | </refsect1> | |
199 | ||
200 | <refsect1> | |
201 | <title>See also</title> | |
202 | ||
203 | <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> | |
204 | </refsect1> | |
205 | </refentry> |