man: document calendar timers
This commit is contained in:
parent
0979f2855c
commit
7a529f63e6
|
@ -477,6 +477,7 @@ MANPAGES = \
|
||||||
man/systemd.kill.5 \
|
man/systemd.kill.5 \
|
||||||
man/systemd.special.7 \
|
man/systemd.special.7 \
|
||||||
man/systemd.journal-fields.7 \
|
man/systemd.journal-fields.7 \
|
||||||
|
man/systemd.time.7 \
|
||||||
man/kernel-command-line.7 \
|
man/kernel-command-line.7 \
|
||||||
man/daemon.7 \
|
man/daemon.7 \
|
||||||
man/bootup.7 \
|
man/bootup.7 \
|
||||||
|
@ -746,7 +747,8 @@ XML_DIRECTIVE_FILES = \
|
||||||
man/systemd.kill.xml \
|
man/systemd.kill.xml \
|
||||||
man/systemd.device.xml \
|
man/systemd.device.xml \
|
||||||
man/systemd.conf.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)
|
man/systemd.directives.xml: make-directive-index.py $(XML_DIRECTIVE_FILES)
|
||||||
$(AM_V_at)$(MKDIR_P) $(dir $@)
|
$(AM_V_at)$(MKDIR_P) $(dir $@)
|
||||||
|
|
291
man/systemd.time.xml
Normal file
291
man/systemd.time.xml
Normal file
|
@ -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>
|
|
@ -105,7 +105,7 @@
|
||||||
<term><varname>OnUnitActiveSec=</varname></term>
|
<term><varname>OnUnitActiveSec=</varname></term>
|
||||||
<term><varname>OnUnitInactiveSec=</varname></term>
|
<term><varname>OnUnitInactiveSec=</varname></term>
|
||||||
|
|
||||||
<listitem><para>Defines timers
|
<listitem><para>Defines monotonic timers
|
||||||
relative to different starting points:
|
relative to different starting points:
|
||||||
<varname>OnActiveSec=</varname> defines a
|
<varname>OnActiveSec=</varname> defines a
|
||||||
timer relative to the moment the timer
|
timer relative to the moment the timer
|
||||||
|
@ -139,8 +139,8 @@
|
||||||
seconds. Example: "OnBootSec=50" means
|
seconds. Example: "OnBootSec=50" means
|
||||||
50s after boot-up. The argument may
|
50s after boot-up. The argument may
|
||||||
also include time units. Example:
|
also include time units. Example:
|
||||||
"OnBootSec=5h 30min" means 5 hours and 30
|
"OnBootSec=5h 30min" means 5 hours and
|
||||||
minutes after boot-up. For details
|
30 minutes after boot-up. For details
|
||||||
about the syntax of time spans see
|
about the syntax of time spans see
|
||||||
<citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para>
|
<citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para>
|
||||||
|
|
||||||
|
@ -152,14 +152,27 @@
|
||||||
elapse and the configured unit is
|
elapse and the configured unit is
|
||||||
started. This is not the case for
|
started. This is not the case for
|
||||||
timers defined in the other
|
timers defined in the other
|
||||||
directives.</para></listitem>
|
directives.</para>
|
||||||
|
|
||||||
<para>These are monotonic timers,
|
<para>These are monotonic timers,
|
||||||
independent of wall-clock time and timezones. If the
|
independent of wall-clock time and timezones. If the
|
||||||
computer is temporarily suspended, the
|
computer is temporarily suspended, the
|
||||||
monotonic clock stops too.</para>
|
monotonic clock stops too.</para></listitem>
|
||||||
|
|
||||||
</varlistentry>
|
</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>
|
<varlistentry>
|
||||||
<term><varname>Unit=</varname></term>
|
<term><varname>Unit=</varname></term>
|
||||||
|
|
||||||
|
@ -185,7 +198,8 @@
|
||||||
<citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
|
<citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
|
||||||
<citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
|
<citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
|
||||||
<citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</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>
|
</para>
|
||||||
</refsect1>
|
</refsect1>
|
||||||
|
|
||||||
|
|
|
@ -111,7 +111,7 @@
|
||||||
the values are added up. Example: "50" refers to 50
|
the values are added up. Example: "50" refers to 50
|
||||||
seconds; "2min 200ms" refers to 2 minutes plus 200
|
seconds; "2min 200ms" refers to 2 minutes plus 200
|
||||||
milliseconds, i.e. 120200ms. The following time units
|
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
|
<para>Empty lines and lines starting with # or ; are
|
||||||
ignored. This may be used for commenting. Lines ending
|
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.path</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
|
||||||
<citerefentry><refentrytitle>systemd.timer</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.snapshot</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
|
||||||
|
<citerefentry><refentrytitle>systemd.time</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
|
||||||
<citerefentry><refentrytitle>capabilities</refentrytitle><manvolnum>7</manvolnum></citerefentry>
|
<citerefentry><refentrytitle>capabilities</refentrytitle><manvolnum>7</manvolnum></citerefentry>
|
||||||
</para>
|
</para>
|
||||||
</refsect1>
|
</refsect1>
|
||||||
|
|
Loading…
Reference in a new issue