]>
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> | |
28 | is a system service that can be used to control the system time and related settings. This page | |
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 | ||
37 | <programlisting> | |
38 | $ gdbus introspect --system \ | |
39 | --dest org.freedesktop.timedate1 \ | |
40 | --object-path /org/freedesktop/timedate1 | |
41 | ||
42 | node /org/freedesktop/timedate1 { | |
43 | interface org.freedesktop.timedate1 { | |
44 | methods: | |
45 | SetTime(in x usec_utc, | |
46 | in b relative, | |
47 | in b user_interaction); | |
48 | SetTimezone(in s timezone, | |
49 | in b user_interaction); | |
50 | SetLocalRTC(in b local_rtc, | |
51 | in b fix_system, | |
52 | in b user_interaction); | |
53 | SetNTP(in b use_ntp, | |
54 | in b user_interaction); | |
55 | signals: | |
56 | properties: | |
57 | readonly s Timezone = 'Europe/Berlin'; | |
58 | readonly b LocalRTC = false; | |
59 | readonly b NTP = true; | |
60 | }; | |
61 | interface org.freedesktop.DBus.Properties { | |
62 | }; | |
63 | interface org.freedesktop.DBus.Introspectable { | |
64 | }; | |
65 | interface org.freedesktop.DBus.Peer { | |
66 | }; | |
67 | }; | |
68 | </programlisting> | |
69 | ||
70 | <refsect2> | |
71 | <title>Methods</title> | |
72 | ||
73 | <para>Use <function>SetTime()</function> to change the system clock. Pass a value of microseconds since | |
74 | the UNIX epoch (1 Jan 1970 UTC). If <varname>relative</varname> is true, the passed usec value will be | |
75 | added to the current system time, if it is false the current system time will be set to the passed usec | |
76 | value. If the system time is set with this call the RTC will be updated as well.</para> | |
77 | ||
78 | <para>Use <function>SetTimezone()</function> to set the system timezone. Pass a value like | |
79 | <literal>Europe/Berlin</literal> to set the timezone. Valid timezones are listed in | |
80 | <filename>/usr/share/zoneinfo/zone.tab</filename>. If the RTC is configured to be maintained in local | |
81 | time, it will be updated accordingly.</para> | |
82 | ||
83 | <para>Use <function>SetLocalRTC()</function> to control whether the RTC is in local time or UTC. It is | |
84 | strongly recommended to maintain the RTC in UTC. Some OSes (Windows) however maintain the RTC in local | |
85 | time, which might make it necessary to enable this feature. However, this creates various problems as | |
86 | daylight changes might be missed. If <varname>fix_system</varname> is passed <literal>true</literal>, | |
87 | the time from the RTC is read again and the system clock adjusted according to the new setting. If | |
88 | <varname>fix_system</varname> is passed <literal>false</literal> the system time is written to the RTC | |
89 | taking the new setting into account. Use <varname>fix_system=true</varname> in installers and livecds | |
90 | where the RTC is probably more reliable than the system time. Use <varname>fix_system=false</varname> | |
91 | in configuration UIs that are run during normal operation and where the system clock is probably more | |
92 | reliable than the RTC.</para> | |
93 | ||
94 | <para>Use <function>SetNTP()</function> to control whether the system clock is synchronized with the | |
95 | network using <filename>systemd-timesyncd</filename>. This will enable and start or disable and stop | |
96 | the chosen time synchronization service.</para> | |
97 | ||
98 | <para>Whenever the timezone and local_rtc settings are changed via the daemon | |
99 | <function>PropertyChanged</function> signals are sent out to which clients can subscribe. Changing the | |
100 | time settings using this interface is authenticated via PolicyKit.</para> | |
101 | ||
102 | <para>Note that this service will not inform you about system time changes. Use | |
103 | <citerefentry project='man-pages'><refentrytitle>timerfd</refentrytitle><manvolnum>3</manvolnum></citerefentry> | |
104 | with <constant>CLOCK_REALTIME</constant> and <constant>TFD_TIMER_CANCEL_ON_SET</constant> for that. | |
105 | </para> | |
106 | ||
107 | <para>The <varname>user_interaction</varname> boolean parameters can be used to control whether | |
108 | PolicyKit should interactively ask the user for authentication credentials if it needs to.</para> | |
109 | ||
110 | <para>The PolicyKit action for <function>SetTimezone()</function> is | |
111 | <interfacename>org.freedesktop.timedate1.set-timezone</interfacename>. For | |
112 | <function>SetLocalRTC()</function> it is | |
113 | <interfacename>org.freedesktop.timedate1.set-local-rtc</interfacename>, for | |
114 | <function>SetTime()</function> it is <interfacename>org.freedesktop.timedate1.set-time</interfacename> | |
115 | and for <function>SetNTP()</function> it is | |
116 | <interfacename>org.freedesktop.timedate1.set-ntp</interfacename>.</para> | |
117 | </refsect2> | |
118 | </refsect1> | |
119 | ||
120 | <refsect1> | |
121 | <title>Versioning</title> | |
122 | ||
123 | <para>These D-Bus interfaces follow <ulink url="http://0pointer.de/blog/projects/versioning-dbus.html"> | |
124 | the usual interface versioning guidelines</ulink>.</para> | |
125 | </refsect1> | |
126 | ||
127 | <refsect1> | |
128 | <title>See also</title> | |
129 | ||
130 | <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> | |
131 | </refsect1> | |
132 | </refentry> |