'\" t .TH "ORG\&.FREEDESKTOP\&.TIMEDATE1" "5" "" "systemd 255" "org.freedesktop.timedate1" .\" ----------------------------------------------------------------- .\" * Define some portability stuff .\" ----------------------------------------------------------------- .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .\" http://bugs.debian.org/507673 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" ----------------------------------------------------------------- .\" * set default formatting .\" ----------------------------------------------------------------- .\" disable hyphenation .nh .\" disable justification (adjust text to left margin only) .ad l .\" ----------------------------------------------------------------- .\" * MAIN CONTENT STARTS HERE * .\" ----------------------------------------------------------------- .SH "NAME" org.freedesktop.timedate1 \- The D\-Bus interface of systemd\-timedated .SH "INTRODUCTION" .PP \fBsystemd-timedated.service\fR(8) is a system service that can be used to control the system time and related settings\&. This page describes the D\-Bus interface\&. .SH "THE D\-BUS API" .PP The service exposes the following interfaces on the bus: .sp .if n \{\ .RS 4 .\} .nf 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 = \*(Aq\&.\&.\&.\*(Aq; 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 { \&.\&.\&. }; }; .fi .if n \{\ .RE .\} .SS "Methods" .PP Use \fBSetTime()\fR to change the system clock\&. Pass a value of microseconds since the UNIX epoch (1 Jan 1970 UTC)\&. If \fIrelative\fR 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\&. .PP Use \fBSetTimezone()\fR to set the system timezone\&. Pass a value like "Europe/Berlin" to set the timezone\&. Valid timezones are listed in /usr/share/zoneinfo/zone\&.tab\&. If the RTC is configured to be maintained in local time, it will be updated accordingly\&. .PP Use \fBSetLocalRTC()\fR 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 \fIfix_system\fR is "true", the time from the RTC is read again and the system clock is adjusted according to the new setting\&. If \fIfix_system\fR is "false", the system time is written to the RTC taking the new setting into account\&. Use \fIfix_system=true\fR in installers and livecds where the RTC is probably more reliable than the system time\&. Use \fIfix_system=false\fR in configuration UIs that are run during normal operation and where the system clock is probably more reliable than the RTC\&. .PP Use \fBSetNTP()\fR to control whether the system clock is synchronized with the network using systemd\-timesyncd\&. This will enable and start or disable and stop the chosen time synchronization service\&. .PP \fBListTimezones()\fR returns a list of time zones known on the local system as an array of names ("["Africa/Abidjan", "Africa/Accra", \&.\&.\&., "UTC"]")\&. .SS "Properties" .PP \fITimezone\fR shows the currently configured time zone\&. \fILocalRTC\fR shows whether the RTC is configured to use UTC (false), or the local time zone (true)\&. \fICanNTP\fR shows whether a service to perform time synchronization over the network is available, and \fINTP\fR shows whether such a service is enabled\&. .PP \fINTPSynchronized\fR shows whether the kernel reports the time as synchronized (c\&.f\&. \fBadjtimex\fR(3))\&. \fITimeUSec\fR and \fIRTCTimeUSec\fR 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\&. .PP Whenever the \fITimezone\fR and \fILocalRTC\fR settings are changed via the daemon, \fBPropertyChanged\fR signals are sent out to which clients can subscribe\&. .PP Note that this service will not inform you about system time changes\&. Use \fBtimerfd\fR(3) with \fBCLOCK_REALTIME\fR and \fBTFD_TIMER_CANCEL_ON_SET\fR for that\&. .SS "Security" .PP The \fIinteractive\fR boolean parameters can be used to control whether \m[blue]\fBpolkit\fR\m[]\&\s-2\u[1]\d\s+2 should interactively ask the user for authentication credentials if required\&. .PP The polkit action for \fBSetTimezone()\fR is org\&.freedesktop\&.timedate1\&.set\-timezone\&. For \fBSetLocalRTC()\fR it is org\&.freedesktop\&.timedate1\&.set\-local\-rtc, for \fBSetTime()\fR it is org\&.freedesktop\&.timedate1\&.set\-time and for \fBSetNTP()\fR it is org\&.freedesktop\&.timedate1\&.set\-ntp\&. \fBListTimezones()\fR does not require any privileges\&. .SH "EXAMPLES" .PP \fBExample\ \&1.\ \&Introspect org\&.freedesktop\&.timedate1 on the bus\fR .sp .if n \{\ .RS 4 .\} .nf $ gdbus introspect \-\-system \e \-\-dest org\&.freedesktop\&.timedate1 \e \-\-object\-path /org/freedesktop/timedate1 .fi .if n \{\ .RE .\} .SH "VERSIONING" .PP These D\-Bus interfaces follow \m[blue]\fBthe usual interface versioning guidelines\fR\m[]\&\s-2\u[2]\d\s+2\&. .SH "SEE ALSO" .PP \m[blue]\fBMore information on how the system clock and RTC interact\fR\m[]\&\s-2\u[3]\d\s+2 .SH "NOTES" .IP " 1." 4 polkit .RS 4 \%https://www.freedesktop.org/software/polkit/docs/latest/ .RE .IP " 2." 4 the usual interface versioning guidelines .RS 4 \%https://0pointer.de/blog/projects/versioning-dbus.html .RE .IP " 3." 4 More information on how the system clock and RTC interact .RS 4 \%https://lists.freedesktop.org/archives/systemd-devel/2011-May/002526.html .RE