Debian Codegraph @

upstream/debian-unstable/man5/org.freedesktop.timedate1.5

raw
1 '\" t
2 .TH "ORG\&.FREEDESKTOP\&.TIMEDATE1" "5" "" "systemd 261~rc3" "org.freedesktop.timedate1"
3 .\" -----------------------------------------------------------------
4 .\" * Define some portability stuff
5 .\" -----------------------------------------------------------------
6 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
7 .\" http://bugs.debian.org/507673
8 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
9 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
10 .ie \n(.g .ds Aq \(aq
11 .el .ds Aq '
12 .\" -----------------------------------------------------------------
13 .\" * set default formatting
14 .\" -----------------------------------------------------------------
15 .\" disable hyphenation
16 .nh
17 .\" disable justification (adjust text to left margin only)
18 .ad l
19 .\" -----------------------------------------------------------------
20 .\" * MAIN CONTENT STARTS HERE *
21 .\" -----------------------------------------------------------------
22 .SH "NAME"
23 org.freedesktop.timedate1 \- The D\-Bus interface of systemd\-timedated
24 .SH "INTRODUCTION"
25 .PP
26 \fBsystemd-timedated.service\fR(8)
27 is a system service that can be used to control the system time and related settings\&. This page describes the D\-Bus interface\&.
28 .SH "THE D\-BUS API"
29 .PP
30 The service exposes the following interfaces on the bus:
31 .sp
32 .if n \{\
33 .RS 4
34 .\}
35 .nf
36 node /org/freedesktop/timedate1 {
37 interface org\&.freedesktop\&.timedate1 {
38 methods:
39 SetTime(in x usec_utc,
40 in b relative,
41 in b interactive);
42 SetTimezone(in s timezone,
43 in b interactive);
44 SetLocalRTC(in b local_rtc,
45 in b fix_system,
46 in b interactive);
47 SetNTP(in b use_ntp,
48 in b interactive);
49 ListTimezones(out as timezones);
50 properties:
51 readonly s Timezone = \*(Aq\&.\&.\&.\*(Aq;
52 readonly b LocalRTC = \&.\&.\&.;
53 @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false")
54 readonly b CanNTP = \&.\&.\&.;
55 readonly b NTP = \&.\&.\&.;
56 @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false")
57 readonly b NTPSynchronized = \&.\&.\&.;
58 @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false")
59 readonly t TimeUSec = \&.\&.\&.;
60 @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false")
61 readonly t RTCTimeUSec = \&.\&.\&.;
62 };
63 interface org\&.freedesktop\&.DBus\&.Peer { \&.\&.\&. };
64 interface org\&.freedesktop\&.DBus\&.Introspectable { \&.\&.\&. };
65 interface org\&.freedesktop\&.DBus\&.Properties { \&.\&.\&. };
66 };
67 .fi
68 .if n \{\
69 .RE
70 .\}
71
72
73
74
75
76
77
78
79
80
81
82
83
84 .SS "Methods"
85 .PP
86 Use
87 \fBSetTime()\fR
88 to change the system clock\&. Pass a value of microseconds since the UNIX epoch (1 Jan 1970 UTC)\&. If
89 \fIrelative\fR
90 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\&.
91 .PP
92 Use
93 \fBSetTimezone()\fR
94 to set the system timezone\&. Pass a value like
95 "Europe/Berlin"
96 to set the timezone\&. Valid timezones are listed in
97 /usr/share/zoneinfo/zone\&.tab\&. If the RTC is configured to be maintained in local time, it will be updated accordingly\&.
98 .PP
99 Use
100 \fBSetLocalRTC()\fR
101 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
102 \fIfix_system\fR
103 is
104 "true", the time from the RTC is read again and the system clock is adjusted according to the new setting\&. If
105 \fIfix_system\fR
106 is
107 "false", the system time is written to the RTC taking the new setting into account\&. Use
108 \fIfix_system=true\fR
109 in installers and livecds where the RTC is probably more reliable than the system time\&. Use
110 \fIfix_system=false\fR
111 in configuration UIs that are run during normal operation and where the system clock is probably more reliable than the RTC\&.
112 .PP
113 Use
114 \fBSetNTP()\fR
115 to control whether the system clock is synchronized with the network using
116 systemd\-timesyncd\&. This will enable and start or disable and stop the chosen time synchronization service\&.
117 .PP
118 \fBListTimezones()\fR
119 returns a list of time zones known on the local system as an array of names ("["Africa/Abidjan", "Africa/Accra", \&.\&.\&., "UTC"]")\&.
120 .SS "Properties"
121 .PP
122 \fITimezone\fR
123 shows the currently configured time zone\&.
124 \fILocalRTC\fR
125 shows whether the RTC is configured to use UTC (false), or the local time zone (true)\&.
126 \fICanNTP\fR
127 shows whether a service to perform time synchronization over the network is available, and
128 \fINTP\fR
129 shows whether such a service is enabled\&.
130 .PP
131 \fINTPSynchronized\fR
132 shows whether the kernel reports the time as synchronized (c\&.f\&.
133 \fBadjtimex\fR(3))\&.
134 \fITimeUSec\fR
135 and
136 \fIRTCTimeUSec\fR
137 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\&.
138 .PP
139 Whenever the
140 \fITimezone\fR
141 and
142 \fILocalRTC\fR
143 settings are changed via the daemon,
144 \fBPropertyChanged\fR
145 signals are sent out to clients which have subscribed\&.
146 .PP
147 Note that this service will not inform you about system time changes\&. Use
148 \fBtimerfd\fR(3)
149 with
150 \fBCLOCK_REALTIME\fR
151 and
152 \fBTFD_TIMER_CANCEL_ON_SET\fR
153 for that\&.
154 .SS "Security"
155 .PP
156 The
157 \fIinteractive\fR
158 boolean parameters can be used to control whether
159 \m[blue]\fBpolkit\fR\m[]\&\s-2\u[1]\d\s+2
160 should interactively ask the user for authentication credentials if required\&.
161 .PP
162 The polkit action for
163 \fBSetTimezone()\fR
164 is
165 org\&.freedesktop\&.timedate1\&.set\-timezone\&. For
166 \fBSetLocalRTC()\fR
167 it is
168 org\&.freedesktop\&.timedate1\&.set\-local\-rtc, for
169 \fBSetTime()\fR
170 it is
171 org\&.freedesktop\&.timedate1\&.set\-time
172 and for
173 \fBSetNTP()\fR
174 it is
175 org\&.freedesktop\&.timedate1\&.set\-ntp\&.
176 \fBListTimezones()\fR
177 does not require any privileges\&.
178 .SH "EXAMPLES"
179 .PP
180 \fBExample\ \&1.\ \&Introspect org\&.freedesktop\&.timedate1 on the bus\fR
181 .sp
182 .if n \{\
183 .RS 4
184 .\}
185 .nf
186 $ gdbus introspect \-\-system \e
187 \-\-dest org\&.freedesktop\&.timedate1 \e
188 \-\-object\-path /org/freedesktop/timedate1
189 .fi
190 .if n \{\
191 .RE
192 .\}
193 .SH "VERSIONING"
194 .PP
195 These D\-Bus interfaces follow
196 \m[blue]\fBthe usual interface versioning guidelines\fR\m[]\&\s-2\u[2]\d\s+2\&.
197 .SH "SEE ALSO"
198 .PP
199 \fBsystemd\fR(1), \fBsystemd-timedated.service\fR(8), \fBtimedatectl\fR(1), \m[blue]\fBMore information on how the system clock and RTC interact\fR\m[]\&\s-2\u[3]\d\s+2
200 .SH "NOTES"
201 .IP " 1." 4
202 polkit
203 .RS 4
204 \%https://www.freedesktop.org/software/polkit/docs/latest/
205 .RE
206 .IP " 2." 4
207 the usual interface versioning guidelines
208 .RS 4
209 \%https://0pointer.de/blog/projects/versioning-dbus.html
210 .RE
211 .IP " 3." 4
212 More information on how the system clock and RTC interact
213 .RS 4
214 \%https://lists.freedesktop.org/archives/systemd-devel/2011-May/002526.html
215 .RE