summaryrefslogtreecommitdiff
path: root/man/systemd.time.xml
diff options
context:
space:
mode:
Diffstat (limited to 'man/systemd.time.xml')
-rw-r--r--man/systemd.time.xml525
1 files changed, 256 insertions, 269 deletions
diff --git a/man/systemd.time.xml b/man/systemd.time.xml
index 2e64089c29..da0729725d 100644
--- a/man/systemd.time.xml
+++ b/man/systemd.time.xml
@@ -1,6 +1,6 @@
<?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">
+ "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
<!--
This file is part of systemd.
@@ -23,288 +23,275 @@
<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, time spans, and calendar
- events are displayed and may be specified in closely
- related syntaxes.</para>
- </refsect1>
-
- <refsect1>
- <title>Displaying Time Spans</title>
-
- <para>Time spans refer to time durations. On display,
- systemd will present time spans 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 Time Spans</title>
-
- <para>When parsing, systemd will accept the same
- time span 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 time span allows for this.</para>
-
- <para>Examples for valid time span specifications:</para>
-
- <programlisting>2 h
+ <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, time spans, and calendar events are
+ displayed and may be specified in closely related syntaxes.</para>
+ </refsect1>
+
+ <refsect1>
+ <title>Displaying Time Spans</title>
+
+ <para>Time spans refer to time durations. On display, systemd will
+ present time spans 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 Time Spans</title>
+
+ <para>When parsing, systemd will accept the same time span 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 time span allows for this.</para>
+
+ <para>Examples for valid time span 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 weekday 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 weekday specification is optional,
- but when the weekday is specified it must either be
- in the abbreviated (<literal>Wed</literal>) or
- non-abbreviated (<literal>Wednesday</literal>) English
- language form (case does not 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 weekday
- 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 time span (see above) that is
- prefixed with <literal>+</literal> is evaluated to the
- current time plus the specified time
- span. Correspondingly, a time span that is prefixed
- with <literal>-</literal> is evaluated to the current
- time minus the specified time span. Instead of
- prefixing the time span with <literal>+</literal> or
- <literal>-</literal>, it may also be suffixed with a
- space and the word <literal>left</literal> or
- <literal>ago</literal>.</para>
-
- <para>Finally, a timespan prefixed with
- <literal>@</literal> is evaluated relative to the UNIX
- time epoch 1st Jan, 1970, 00:00.</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
+ </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 weekday 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 weekday specification is optional, but
+ when the weekday is specified it must either be in the abbreviated
+ (<literal>Wed</literal>) or non-abbreviated
+ (<literal>Wednesday</literal>) English language form (case does
+ not 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 weekday 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 time span (see above) that is prefixed with
+ <literal>+</literal> is evaluated to the current time plus the
+ specified time span. Correspondingly, a time span that is prefixed
+ with <literal>-</literal> is evaluated to the current time minus
+ the specified time span. Instead of prefixing the time span with
+ <literal>+</literal> or <literal>-</literal>, it may also be
+ suffixed with a space and the word <literal>left</literal> or
+ <literal>ago</literal>.</para>
+
+ <para>Finally, a timespan prefixed with <literal>@</literal> is
+ evaluated relative to the UNIX time epoch 1st Jan, 1970,
+ 00:00.</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
- @1395716396 → Tue 2014-03-25 03:59:56</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 weekday while
- parsing only accepts English weekday 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, but only if that
- day is a Thursday or Friday.</para>
-
- <para>The weekday specification is optional. If
- specified, it should consist of one or more English
- language weekday names, either in the abbreviated
- (Wed) or non-abbreviated (Wednesday) form (case does
- not matter), separated by commas. Specifying two
- weekdays separated by <literal>-</literal> refers to a
- range of continuous weekdays. <literal>,</literal> and
- <literal>-</literal> may be combined freely.</para>
-
- <para>In the date and time specifications, any
- component may be specified as <literal>*</literal> in
- which case any value will match. Alternatively, each
- component can be specified as a list of values separated
- by commas. Values may also be suffixed with
- <literal>/</literal> 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, <literal>:00</literal> is assumed.</para>
-
- <para>Timezone names may not be specified.</para>
-
- <para>The special expressions
- <literal>minutely</literal>,
- <literal>hourly</literal>, <literal>daily</literal>,
- <literal>monthly</literal>, <literal>weekly</literal>,
- <literal>yearly</literal>,
- <literal>quarterly</literal>,
- <literal>semiannually</literal> may be used as
- calendar events which refer to
- <literal>*-*-* *:*:00</literal>,
- <literal>*-*-* *:00:00</literal>,
- <literal>*-*-* 00:00:00</literal>,
- <literal>*-*-01 00:00:00</literal>,
- <literal>Mon *-*-* 00:00:00</literal>,
- <literal>*-01-01 00:00:00</literal>,
- <literal>*-01,04,07,10-01 00:00:0</literal> and
- <literal>*-01,07-01 00:00:00</literal> respectively.
- </para>
-
- <para>Examples for valid timestamps and their
- normalized form:</para>
+ 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
+ @1395716396 → Tue 2014-03-25 03:59:56</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 weekday while parsing only accepts English weekday
+ 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, but only if that day is a Thursday or
+ Friday.</para>
+
+ <para>The weekday specification is optional. If specified, it
+ should consist of one or more English language weekday names,
+ either in the abbreviated (Wed) or non-abbreviated (Wednesday)
+ form (case does not matter), separated by commas. Specifying two
+ weekdays separated by <literal>-</literal> refers to a range of
+ continuous weekdays. <literal>,</literal> and <literal>-</literal>
+ may be combined freely.</para>
+
+ <para>In the date and time specifications, any component may be
+ specified as <literal>*</literal> in which case any value will
+ match. Alternatively, each component can be specified as a list of
+ values separated by commas. Values may also be suffixed with
+ <literal>/</literal> 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, <literal>:00</literal> is
+ assumed.</para>
+
+ <para>Timezone names may not be specified.</para>
+
+ <para>The special expressions
+ <literal>minutely</literal>,
+ <literal>hourly</literal>, <literal>daily</literal>,
+ <literal>monthly</literal>, <literal>weekly</literal>,
+ <literal>yearly</literal>,
+ <literal>quarterly</literal>,
+ <literal>semiannually</literal> may be used as
+ calendar events which refer to
+ <literal>*-*-* *:*:00</literal>,
+ <literal>*-*-* *:00:00</literal>,
+ <literal>*-*-* 00:00:00</literal>,
+ <literal>*-*-01 00:00:00</literal>,
+ <literal>Mon *-*-* 00:00:00</literal>,
+ <literal>*-01-01 00:00:00</literal>,
+ <literal>*-01,04,07,10-01 00:00:0</literal> and
+ <literal>*-01,07-01 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 *-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
+ *-*-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
+ 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
- yearly → *-01-01 00:00:00
- annually → *-01-01 00:00:00
- *:2/3 → *-*-* *:02/3:00</programlisting>
-
- <para>Calendar events are used by timer units, see
- <citerefentry><refentrytitle>systemd.timer</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>,
- <citerefentry><refentrytitle>systemd.directives</refentrytitle><manvolnum>7</manvolnum></citerefentry>
- </para>
- </refsect1>
+ 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
+ yearly → *-01-01 00:00:00
+ annually → *-01-01 00:00:00
+ *:2/3 → *-*-* *:02/3:00</programlisting>
+
+ <para>Calendar events are used by timer units, see
+ <citerefentry><refentrytitle>systemd.timer</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>,
+ <citerefentry><refentrytitle>systemd.directives</refentrytitle><manvolnum>7</manvolnum></citerefentry>
+ </para>
+ </refsect1>
</refentry>