From b8af9fd65b697e9bb77a32d1a6a70367814aaed5 Mon Sep 17 00:00:00 2001

From: Lennart Poettering <lennart@poettering.net>

Date: Mon, 1 Apr 2019 17:30:45 +0200

Subject: [PATCH] man: be clearer that .timer time expressions need to be reset

 to override them

let's be clearer about the overriding concept for OnCalendar= settings.

Prompted by this thread:

https://lists.freedesktop.org/archives/systemd-devel/2019-March/042351.html

(cherry picked from commit 58031d99c6320855b86f4890baa9165597e3d841)

Resolves: #1816908

---

 man/systemd.timer.xml | 31 ++++++++++++++++++-------------

 1 file changed, 18 insertions(+), 13 deletions(-)

diff --git a/man/systemd.timer.xml b/man/systemd.timer.xml

index 44b257c745..ebc1df89f1 100644

--- a/man/systemd.timer.xml

+++ b/man/systemd.timer.xml

@@ -125,12 +125,12 @@

         to when the unit the timer is activating was last

         deactivated.</para>

-        <para>Multiple directives may be combined of the same and of

-        different types. For example, by combining

-        <varname>OnBootSec=</varname> and

-        <varname>OnUnitActiveSec=</varname>, it is possible to define

-        a timer that elapses in regular intervals and activates a

-        specific service each time.</para>

+        <para>Multiple directives may be combined of the same and of different types, in which case the timer

+        unit will trigger whenever any of the specified timer expressions elapse. For example, by combining

+        <varname>OnBootSec=</varname> and <varname>OnUnitActiveSec=</varname>, it is possible to define a

+        timer that elapses in regular intervals and activates a specific service each time. Moreover, both

+        monotonic time expressions and <varname>OnCalendar=</varname> calendar expressions may be combined in

+        the same timer unit.</para>

         <para>The arguments to the directives are time spans

         configured in seconds. Example: "OnBootSec=50" means 50s after

@@ -145,13 +145,12 @@

         and the configured unit is started. This is not the case for

         timers defined in the other directives.</para>

-        <para>These are monotonic timers, independent of wall-clock

-        time and timezones. If the computer is temporarily suspended,

-        the monotonic clock stops too.</para>

+        <para>These are monotonic timers, independent of wall-clock time and timezones. If the computer is

+        temporarily suspended, the monotonic clock pauses, too.</para>

-        <para>If the empty string is assigned to any of these options,

-        the list of timers is reset, and all prior assignments will

-        have no effect.</para>

+        <para>If the empty string is assigned to any of these options, the list of timers is reset (both

+        monotonic timers and <varname>OnCalendar=</varname> timers, see below), and all prior assignments

+        will have no effect.</para>

         <para>Note that timers do not necessarily expire at the

         precise time configured with these settings, as they are

@@ -175,7 +174,13 @@

         the <varname>AccuracySec=</varname> setting

         below.</para>

-       <para>May be specified more than once.</para></listitem>

+        <para>May be specified more than once, in which case the timer unit will trigger whenever any of the

+        specified expressions elapse. Moreover calendar timers and monotonic timers (see above) may be

+        combined within the same timer unit.</para>

+

+        <para>If the empty string is assigned to any of these options, the list of timers is reset (both

+        <varname>OnCalendar=</varname> timers and monotonic timers, see above), and all prior assignments

+        will have no effect.</para></listitem>

       </varlistentry>

       <varlistentry>