diff options
| -rw-r--r-- | Makefile.am | 4 | ||||
| -rw-r--r-- | man/systemd.time.xml | 291 | ||||
| -rw-r--r-- | man/systemd.timer.xml | 26 | ||||
| -rw-r--r-- | man/systemd.unit.xml | 3 |
4 files changed, 316 insertions, 8 deletions
diff --git a/Makefile.am b/Makefile.am index 5d772be94..632184092 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 000000000..8e44e3ddd --- /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 6fc26a553..5cc543e45 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 c20efe552..35644d38a 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> |