man: document calendar timers

4 files changed, 316 insertions, 8 deletions

diff --git a/Makefile.am b/Makefile.am
index 5d772be942..6321840921 100644
--- a/Makefile.am
+++ b/Makefile.am
@@ -477,6 +477,7 @@ MANPAGES = \
 	man/systemd.kill.5 \
 	man/systemd.special.7 \
 	man/systemd.journal-fields.7 \
+	man/systemd.time.7 \
 	man/kernel-command-line.7 \
 	man/daemon.7 \
 	man/bootup.7 \
@@ -746,7 +747,8 @@ XML_DIRECTIVE_FILES = \
 	man/systemd.kill.xml \
 	man/systemd.device.xml \
 	man/systemd.conf.xml \
-	man/systemd.journal-fields.xml
+	man/systemd.journal-fields.xml \
+	man/systemd.time.xml
 
 man/systemd.directives.xml: make-directive-index.py $(XML_DIRECTIVE_FILES)
 	$(AM_V_at)$(MKDIR_P) $(dir $@)
diff --git a/man/systemd.time.xml b/man/systemd.time.xml
new file mode 100644
index 0000000000..8e44e3ddde
--- /dev/null
+++ b/man/systemd.time.xml
@@ -0,0 +1,291 @@
+<?xml version='1.0'?> <!--*-nxml-*-->
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+        "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
+
+<!--
+  This file is part of systemd.
+
+  Copyright 2010 Lennart Poettering
+
+  systemd is free software; you can redistribute it and/or modify it
+  under the terms of the GNU Lesser General Public License as published by
+  the Free Software Foundation; either version 2.1 of the License, or
+  (at your option) any later version.
+
+  systemd is distributed in the hope that it will be useful, but
+  WITHOUT ANY WARRANTY; without even the implied warranty of
+  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+  Lesser General Public License for more details.
+
+  You should have received a copy of the GNU Lesser General Public License
+  along with systemd; If not, see <http://www.gnu.org/licenses/>.
+-->
+
+<refentry id="systemd.time">
+
+        <refentryinfo>
+                <title>systemd.time</title>
+                <productname>systemd</productname>
+
+                <authorgroup>
+                        <author>
+                                <contrib>Developer</contrib>
+                                <firstname>Lennart</firstname>
+                                <surname>Poettering</surname>
+                                <email>lennart@poettering.net</email>
+                        </author>
+                </authorgroup>
+        </refentryinfo>
+
+        <refmeta>
+                <refentrytitle>systemd.time</refentrytitle>
+                <manvolnum>7</manvolnum>
+        </refmeta>
+
+        <refnamediv>
+                <refname>systemd.time</refname>
+                <refpurpose>Time and date specifications</refpurpose>
+        </refnamediv>
+
+        <refsect1>
+                <title>Description</title>
+
+                <para>In systemd timestamps, timespans, and calendar
+                events are displayed and may be specified in closely
+                related syntaxes.</para>
+        </refsect1>
+
+        <refsect1>
+                <title>Displaying Timespans</title>
+
+                <para>Timespans refer to time durations. On display
+                systemd will present timespans as a space separated
+                series of time values each suffixed by a time
+                unit.</para>
+
+                <programlisting>2h 30min</programlisting>
+
+                <para>All specified time values are meant to be added
+                up. The above hence refers to 150 minutes.</para>
+        </refsect1>
+
+        <refsect1>
+                <title>Parsing Timespans</title>
+
+                <para>When parsing systemd will accept the same
+                timespan syntax. Separating spaces may be omitted. The
+                following time units are understood:</para>
+
+                <itemizedlist>
+                        <listitem><para>usec, us</para></listitem>
+                        <listitem><para>msec, ms</para></listitem>
+                        <listitem><para>seconds, second, sec, s</para></listitem>
+                        <listitem><para>minutes, minute, min, m</para></listitem>
+                        <listitem><para>hours, hour, hr, h</para></listitem>
+                        <listitem><para>days, day, d</para></listitem>
+                        <listitem><para>weeks, week, w</para></listitem>
+                        <listitem><para>months, month</para></listitem>
+                        <listitem><para>years, year, y</para></listitem>
+                </itemizedlist>
+
+                <para>If no time unit is specified, generally seconds
+                are assumed, but some exceptions exist and are marked
+                as such. In a few cases <literal>ns</literal>,
+                <literal>nsec</literal> is accepted too, where the
+                granularity of the timespan allows for this.</para>
+
+                <para>Examples for valid timespan specifications:</para>
+
+                <programlisting>2 h
+2hours
+48hr
+1y 12month
+55s500ms
+300ms20s 5day</programlisting>
+        </refsect1>
+
+        <refsect1>
+                <title>Displaying Timestamps</title>
+
+                <para>Timestamps refer to specific, unique points in
+                time. On display systemd will format these in the
+                local timezone as follows:</para>
+
+                <programlisting>Fri 2012-11-23 23:02:15 CET</programlisting>
+
+                <para>The week day is printed according to the locale
+                choice of the user.</para>
+        </refsect1>
+
+        <refsect1>
+                <title>Parsing Timestamps</title>
+
+                <para>When parsing systemd will accept a similar
+                timestamp syntax, but excluding any timezone
+                specification (this limitation might be removed
+                eventually). The week day specification is optional,
+                but when the week day is specified it must either be
+                in the abbreviated (<literal>Wed</literal>) or
+                non-abbreviated (<literal>Wednesday</literal>) english
+                language form (case doesn't matter), and is not
+                subject to the locale choice of the user. Either the
+                date, or the time part may be omitted, in which case
+                the current date or 00:00:00, resp., is assumed. The
+                seconds component of the time may also be omitted, in
+                which case ":00" is assumed. Year numbers may be
+                specified in full or may be abbreviated (omitting the
+                century).</para>
+
+                <para>A timestamp is considered invalid if a week day
+                is specified and the date does not actually match the
+                specified day of the week.</para>
+
+                <para>When parsing systemd will also accept a few
+                special placeholders instead of timestamps:
+                <literal>now</literal> may be used to refer to the
+                current time (or of the invocation of the command
+                that is currently executed). <literal>today</literal>,
+                <literal>yesterday</literal>,
+                <literal>tomorrow</literal> refer to 00:00:00 of the
+                current day, the day before or the next day,
+                respectively.</para>
+
+                <para>When parsing systemd will also accept relative
+                time specifications. A timespan (see above) that is
+                prefixed with <literal>+</literal> is evaluated to the
+                current time plus the specified
+                timespan. Correspondingly a timespan that is prefix
+                with <literal>-</literal> is evaluated to the current
+                time minus the specified timespan. Instead of
+                prefixing the timespan with <literal>-</literal> it
+                may also be suffixed with a space and the word
+                <literal>ago</literal>.</para>
+
+                <para>Examples for valid timestamps and their
+                normalized form (assuming the current time was
+                2012-11-23 18:15:22):</para>
+
+                <programlisting>Fri 2012-11-23 11:12:13 → Fri 2012-11-23 11:12:13
+    2012-11-23 11:12:13 → Fri 2012-11-23 11:12:13
+             2012-11-23 → Fri 2012-11-23 00:00:00
+               12-11-23 → Fri 2012-11-23 00:00:00
+               11:12:13 → Fri 2012-11-23 11:12:13
+                  11:12 → Fri 2012-11-23 11:12:00
+                    now → Fri 2012-11-23 18:15:22
+                  today → Fri 2012-11-23 00:00:00
+              yesterday → Fri 2012-11-22 00:00:00
+               tomorrow → Fri 2012-11-24 00:00:00
+               +3h30min → Fri 2012-11-23 21:45:22
+                    -5s → Fri 2012-11-23 18:15:17
+              11min ago → Fri 2012-11-23 18:04:22</programlisting>
+
+                <para>Note that timestamps printed by systemd will not
+                be parsed correctly by systemd, as the timezone
+                specification is not accepted, and printing timestamps
+                is subject to locale settings for the week day while
+                parsing only accepts english week day names.</para>
+
+                <para>In some cases systemd will display a relative
+                timestamp (relative to the current time, or the time
+                of invocation of the command) instead or in addition
+                to an absolute timestamp as described above. A
+                relative timestamp is formatted as follows:</para>
+
+                <para>2 months 5 days ago</para>
+
+                <para>Note that any relative timestamp will also parse
+                correctly where a timestamp is expected. (see above)</para>
+        </refsect1>
+
+        <refsect1>
+                <title>Calendar Events</title>
+
+                <para>Calendar events may be used to refer to one or
+                more points in time in a single expression. They form
+                a superset of the absolute timestamps explained above:</para>
+
+                <programlisting>Thu,Fri 2012-*-1,5 11:12:13</programlisting>
+
+                <para>The above refers to 11:12:13 of the first or
+                fifth day of any month of the year 2012, given that it
+                is a thursday or friday.</para>
+
+                <para>The weekday specification is optional. If
+                specified it should consist of one or more english
+                language week day names, either in the abbreviated
+                (Wed) or non-abbreviated (Wednesday) form (case does
+                not matter), separated by colons. Specifying two week
+                days separated by "-" refers to a range of continuous
+                week days. "," and "-" may be combined freely.</para>
+
+                <para>In the date and time specifications any
+                component may be specified as "*" in which case any
+                value will match. Alternatively, each component can be
+                specified as list of values separated by
+                colons. Values may also be suffixed with "/" and a
+                repetition value, which indicates that the value and
+                all values plus multiples of the repetition value are
+                matched.</para>
+
+                <para>Either time or date specification may be
+                omitted, in which case the current day and 00:00:00 is
+                implied, respectively. If the second component is not
+                specified ":00" is assumed.</para>
+
+                <para>Timezone names may not be specified.</para>
+
+                <para>The special expressions
+                <literal>hourly</literal>, <literal>daily</literal>,
+                <literal>monthly</literal> and <literal>weekly</literal>
+                may be used as calendar events which refer to
+                <literal>*-*-* *:00:00</literal>, <literal>*-*-*
+                00:00:00</literal>, <literal>*-*-01 00:00:00</literal> and
+                <literal>Mon *-*-* 00:00:00</literal>,
+                respectively.</para>
+
+                <para>Examples for valid timestamps and their
+                normalized form:</para>
+
+<programlisting>   Sat,Thu,Mon-Wed,Sat-Sun → Mon-Thu,Sat,Sun *-*-* 00:00:00
+     Mon,Sun 12-*-* 2,1:23 → Mon,Sun 2012-*-* 01,02:23:00
+                   Wed *-1 → Wed *-*-01 00:00:00
+           Wed-Wed,Wed *-1 → Wed *-*-01 00:00:00
+                Wed, 17:48 → Wed *-*-* 17:48:00
+Wed-Sat,Tue 12-10-15 1:2:3 → Tue-Sat 2012-10-15 01:02:03
+               *-*-7 0:0:0 → *-*-07 00:00:00
+                     10-15 → *-10-15 00:00:00
+       monday *-12-* 17:00 → Mon *-12-* 17:00:00
+ Mon,Fri *-*-3,1,2 *:30:45 → Mon,Fri *-*-01,02,03 *:30:45
+      12,14,13,12:20,10,30 → *-*-* 12,13,14:10,20,30:00
+ mon,fri *-1/2-1,3 *:30:45 → Mon,Fri *-01/2-01,03 *:30:45
+            03-05 08:05:40 → *-03-05 08:05:40
+                  08:05:40 → *-*-* 08:05:40
+                     05:40 → *-*-* 05:40:00
+    Sat,Sun 12-05 08:05:40 → Sat,Sun *-12-05 08:05:40
+          Sat,Sun 08:05:40 → Sat,Sun *-*-* 08:05:40
+          2003-03-05 05:40 → 2003-03-05 05:40:00
+                2003-03-05 → 2003-03-05 00:00:00
+                     03-05 → *-03-05 00:00:00
+                    hourly → *-*-* *:00:00
+                     daily → *-*-* 00:00:00
+                   monthly → *-*-01 00:00:00
+                    weekly → Mon *-*-* 00:00:00
+                     *:2/3 → *-*-* *:02/3:00</programlisting>
+
+                  <para>Calendar events are used by timer units, see
+                  <citerefentry><refentrytitle>systemd.time</refentrytitle><manvolnum>5</manvolnum></citerefentry>
+                  for details.</para>
+
+        </refsect1>
+
+        <refsect1>
+                  <title>See Also</title>
+                  <para>
+                          <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
+                          <citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
+                          <citerefentry><refentrytitle>systemd.timer</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
+                          <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>
+                  </para>
+        </refsect1>
+
+</refentry>
diff --git a/man/systemd.timer.xml b/man/systemd.timer.xml
index 6fc26a5536..5cc543e453 100644
--- a/man/systemd.timer.xml
+++ b/man/systemd.timer.xml
@@ -105,7 +105,7 @@
                                 <term><varname>OnUnitActiveSec=</varname></term>
                                 <term><varname>OnUnitInactiveSec=</varname></term>
 
-                                <listitem><para>Defines timers
+                                <listitem><para>Defines monotonic timers
                                 relative to different starting points:
                                 <varname>OnActiveSec=</varname> defines a
                                 timer relative to the moment the timer
@@ -139,8 +139,8 @@
                                 seconds. Example: "OnBootSec=50" means
                                 50s after boot-up. The argument may
                                 also include time units. Example:
-                                "OnBootSec=5h 30min" means 5 hours and 30
-                                minutes after boot-up. For details
+                                "OnBootSec=5h 30min" means 5 hours and
+                                30 minutes after boot-up. For details
                                 about the syntax of time spans see
                                 <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para>
 
@@ -152,14 +152,27 @@
                                 elapse and the configured unit is
                                 started. This is not the case for
                                 timers defined in the other
-                                directives.</para></listitem>
+                                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>
+                                monotonic clock stops too.</para></listitem>
 
                         </varlistentry>
+
+                        <varlistentry>
+                                <term><varname>OnCalendar=</varname></term>
+
+                                <listitem><para>Defines realtime
+                                (i.e. wallclock) timers via calendar
+                                event expressions. See
+                                <citerefentry><refentrytitle>systemd.time</refentrytitle><manvolnum>7</manvolnum></citerefentry>
+                                for more information on the syntax of
+                                calendar event
+                                expressions.</para></listitem>
+                        </varlistentry>
+
                         <varlistentry>
                                 <term><varname>Unit=</varname></term>
 
@@ -185,7 +198,8 @@
                           <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
                           <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
                           <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
-                          <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>
+                          <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
+                          <citerefentry><refentrytitle>systemd.time</refentrytitle><manvolnum>7</manvolnum></citerefentry>
                   </para>
         </refsect1>
 
diff --git a/man/systemd.unit.xml b/man/systemd.unit.xml
index c20efe5527..35644d38a6 100644
--- a/man/systemd.unit.xml
+++ b/man/systemd.unit.xml
@@ -111,7 +111,7 @@
                 the values are added up. Example: "50" refers to 50
                 seconds; "2min 200ms" refers to 2 minutes plus 200
                 milliseconds, i.e. 120200ms. The following time units
-                are understood: s, min, h, d, w, ms, us.</para>
+                are understood: s, min, h, d, w, ms, us. For details see <citerefentry><refentrytitle>systemd.time</refentrytitle><manvolnum>7</manvolnum></citerefentry>.</para>
 
                 <para>Empty lines and lines starting with # or ; are
                 ignored. This may be used for commenting. Lines ending
@@ -1077,6 +1077,7 @@
                         <citerefentry><refentrytitle>systemd.path</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
                         <citerefentry><refentrytitle>systemd.timer</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
                         <citerefentry><refentrytitle>systemd.snapshot</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
+                        <citerefentry><refentrytitle>systemd.time</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
                         <citerefentry><refentrytitle>capabilities</refentrytitle><manvolnum>7</manvolnum></citerefentry>
                 </para>
         </refsect1>