summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorLennart Poettering <lennart@poettering.net>2012-11-24 00:24:14 +0100
committerLennart Poettering <lennart@poettering.net>2012-11-24 00:24:46 +0100
commit7a529f63e60dfdccc23d61808c20ba40d9901e47 (patch)
treed78fd6cc6c542f5cd71e2d769728053c6a16b10c
parent0979f2855c81d144d4c7d814678a5b5b2d34155b (diff)
man: document calendar timers
-rw-r--r--Makefile.am4
-rw-r--r--man/systemd.time.xml291
-rw-r--r--man/systemd.timer.xml26
-rw-r--r--man/systemd.unit.xml3
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>