diff options
author | Zbigniew Jędrzejewski-Szmek <zbyszek@in.waw.pl> | 2020-04-09 17:17:16 +0200 |
---|---|---|
committer | Zbigniew Jędrzejewski-Szmek <zbyszek@in.waw.pl> | 2020-04-12 19:48:01 +0200 |
commit | 9c970e5f55108456e45b3b2f7617be599ddff516 (patch) | |
tree | ff17871ac5b0b97da47a46d31f6aa041329ae749 /man | |
parent | 106d79be06299cb62a947c9c3ca7f5076db9ae66 (diff) | |
download | systemd-9c970e5f55108456e45b3b2f7617be599ddff516.tar.gz |
man: import org.freedesktop.timedate1(3) from the wiki
Diffstat (limited to 'man')
-rw-r--r-- | man/org.freedesktop.timedate1.xml | 132 | ||||
-rw-r--r-- | man/rules/meson.build | 1 | ||||
-rw-r--r-- | man/systemd-timedated.service.xml | 23 |
3 files changed, 151 insertions, 5 deletions
diff --git a/man/org.freedesktop.timedate1.xml b/man/org.freedesktop.timedate1.xml new file mode 100644 index 0000000000..65a5f5b2fb --- /dev/null +++ b/man/org.freedesktop.timedate1.xml @@ -0,0 +1,132 @@ +<?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+ --> + +<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> +$ gdbus introspect --system \ + --dest org.freedesktop.timedate1 \ + --object-path /org/freedesktop/timedate1 + +node /org/freedesktop/timedate1 { + interface org.freedesktop.timedate1 { + methods: + SetTime(in x usec_utc, + in b relative, + in b user_interaction); + SetTimezone(in s timezone, + in b user_interaction); + SetLocalRTC(in b local_rtc, + in b fix_system, + in b user_interaction); + SetNTP(in b use_ntp, + in b user_interaction); + signals: + properties: + readonly s Timezone = 'Europe/Berlin'; + readonly b LocalRTC = false; + readonly b NTP = true; + }; + interface org.freedesktop.DBus.Properties { + }; + interface org.freedesktop.DBus.Introspectable { + }; + interface org.freedesktop.DBus.Peer { + }; +}; + </programlisting> + + <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 call 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. Some OSes (Windows) however maintain the RTC in local + time, which might make it necessary to enable this feature. However, this creates various problems as + daylight changes might be missed. If <varname>fix_system</varname> is passed <literal>true</literal>, + the time from the RTC is read again and the system clock adjusted according to the new setting. If + <varname>fix_system</varname> is passed <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>Whenever the timezone and local_rtc settings are changed via the daemon + <function>PropertyChanged</function> signals are sent out to which clients can subscribe. Changing the + time settings using this interface is authenticated via PolicyKit.</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> + + <para>The <varname>user_interaction</varname> boolean parameters can be used to control whether + PolicyKit should interactively ask the user for authentication credentials if it needs to.</para> + + <para>The PolicyKit 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>.</para> + </refsect2> + </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> diff --git a/man/rules/meson.build b/man/rules/meson.build index d69286301b..34b775d91a 100644 --- a/man/rules/meson.build +++ b/man/rules/meson.build @@ -48,6 +48,7 @@ manpages = [ ['org.freedesktop.import1', '5', [], 'ENABLE_IMPORTD'], ['org.freedesktop.login1', '5', [], 'ENABLE_LOGIND'], ['org.freedesktop.machine1', '5', [], 'ENABLE_MACHINED'], + ['org.freedesktop.timedate1', '5', [], 'ENABLE_TIMEDATED'], ['os-release', '5', [], ''], ['pam_systemd', '8', [], 'HAVE_PAM'], ['pam_systemd_home', '8', [], 'ENABLE_PAM_HOME'], diff --git a/man/systemd-timedated.service.xml b/man/systemd-timedated.service.xml index f981848cb2..b722b33115 100644 --- a/man/systemd-timedated.service.xml +++ b/man/systemd-timedated.service.xml @@ -29,7 +29,7 @@ <refsect1> <title>Description</title> - <para><filename>systemd-timedated</filename> is a system service + <para><filename>systemd-timedated.service</filename> is a system service that may be used as a mechanism to change the system clock and timezone, as well as to enable/disable network time synchronization. <filename>systemd-timedated</filename> is automatically activated @@ -39,10 +39,23 @@ <citerefentry><refentrytitle>timedatectl</refentrytitle><manvolnum>1</manvolnum></citerefentry> is a command line client to this service.</para> - <para>See the <ulink - url="https://www.freedesktop.org/wiki/Software/systemd/timedated"> - developer documentation</ulink> for information about the APIs - <filename>systemd-timedated</filename> provides.</para> + <para><filename>systemd-timedated</filename> currently offers access to + the following four settings: + <itemizedlist> + <listitem><para>The system time</para></listitem> + + <listitem><para>The system timezone</para></listitem> + + <listitem><para>A boolean controlling whether the system RTC is in local or UTC + timezone</para></listitem> + + <listitem><para>Whether the time synchronization service is enabled/started or + disabled/stopped, see next section.</para></listitem> + </itemizedlist></para> + + <para>See + <citerefentry><refentrytitle>org.freedesktop.timedate1</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for information about the D-Bus API.</para> </refsect1> <refsect1> |