"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
<!--
+ SPDX-License-Identifier: LGPL-2.1+
+
This file is part of systemd.
Copyright 2010 Lennart Poettering
<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>
+ <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. Example:</para>
<programlisting>2h 30min</programlisting>
- <para>All specified time values are meant to be added up. The
- above hence refers to 150 minutes.</para>
+ <para>All specified time values are meant to be added up. The above hence refers to 150 minutes. Display is
+ locale-independent, only English names for the time units are used.</para>
</refsect1>
<refsect1>
<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>
+ <listitem><para>months, month, M (defined as 30.44 days)</para></listitem>
+ <listitem><para>years, year, y (defined as 365.25 days)</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>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 permits this. Parsing is generally locale-independent, non-English names for the time units are not
+ accepted.</para>
<para>Examples for valid time span specifications:</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>
+ <para>The weekday is printed in the abbreviated English language form. The formatting is locale-independent.</para>
+
+ <para>In some cases timestamps are shown in the UTC timezone instead of the local timezone, which is indicated via
+ the <literal>UTC</literal> timezone specifier in the output.</para>
+
+ <para>In some cases timestamps are shown with microsecond granularity. In this case the sub-second remainder is
+ separated by a full stop from the seconds component.</para>
</refsect1>
<refsect1>
<title>Parsing Timestamps</title>
- <para>When parsing systemd will accept a similar syntax, but expects
- no timezone specification, unless it is given as the literal string
- "UTC". In this case the time is considered in UTC time, otherwise in
- the local timezone. 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, respectively, 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 accept a similar syntax, but expects no timezone specification, unless it is given
+ as the literal string <literal>UTC</literal> (for the UTC timezone), or is specified to be the locally configured
+ timezone, or the timezone name in the IANA timezone database format. The complete list of timezones
+ supported on your system can be obtained using the <literal>timedatectl list-timezones</literal>
+ (see <citerefentry><refentrytitle>timedatectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>).
+ Using IANA format is recommended over local timezone names, as less prone to errors (eg: with local timezone it's possible to
+ specify daylight saving time in winter, while it's incorrect). 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,
+ respectively, 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 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,
+ <literal>yesterday</literal>, and <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
(assuming the current time was 2012-11-23 18:15:22 and the timezone
was UTC+8, for example TZ=Asia/Shanghai):</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 11:12:13 UTC → Fri 2012-11-23 19: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:13.9900009 → Fri 2012-11-23 11:12:13
- format_timestamp_us: Fri 2012-11-23 11:12:13.990000
- 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
- today UTC → Fri 2012-11-23 16: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
- +3h30min UTC → -EINVAL
- -5s → Fri 2012-11-23 18:15:17
- 11min ago → Fri 2012-11-23 18:04:22
- 11min ago UTC → -EINVAL
- @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>
+ <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 11:12:13 UTC → Fri 2012-11-23 19: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
+ today UTC → Fri 2012-11-23 16:00:00
+ yesterday → Fri 2012-11-22 00:00:00
+ tomorrow → Fri 2012-11-24 00:00:00
+tomorrow Pacific/Auckland → Thu 2012-11-23 19: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 displayed by remote systems with a non-matching timezone are usually not parsable
+ locally, as the timezone component is not understood (unless it happens to be <literal>UTC</literal>).</para>
+
+ <para>Timestamps may also be specified with microsecond granularity. The sub-second remainder is expected separated
+ by a full stop from the seconds component. Example:</para>
+
+ <programlisting>2014-03-25 03:59:56.654563</programlisting>
+
+ <para>In some cases, systemd will display a relative timestamp (relative to the current time, or the time of
+ invocation of the command) instead of or in addition to an absolute timestamp as described above. A relative
+ timestamp is formatted as follows:</para>
+
+ <programlisting>2 months 5 days ago</programlisting>
+
+ <para>Note that a relative timestamp is also accepted where a timestamp is expected (see above).</para>
</refsect1>
<refsect1>
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>
+ 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
+ values separated by commas. Values may 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>
+ the value itself and the value plus all multiples of the repetition value
+ are matched. Two values separated by <literal>..</literal> may be used
+ to indicate a range of values; ranges may also be followed with
+ <literal>/</literal> and a repetition value.</para>
+
+ <para>A date specification may use <literal>~</literal> to indicate the
+ last day(s) in a month. For example, <literal>*-02~03</literal> means
+ "the third last day in February," and <literal>Mon *-05~07/1</literal>
+ means "the last Monday in May."</para>
+
+ <para>The seconds component may contain decimal fractions both in
+ the value and the repetition. All fractions are rounded to 6
+ decimal places.</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>A timezone specification is not expected, unless it is given
- as the literal string "UTC", similarly to timestamps.</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:00</literal> and
- <literal>*-01,07-01 00:00:00</literal> respectively.
- </para>
+ <para>Timezone can be specified as the literal string <literal>UTC</literal>, or
+ the local timezone, similar to the supported syntax of timestamps (see above), or the timezone
+ in the IANA timezone database format (also see above).</para>
+
+ <para>The following special expressions may be used as shorthands for longer normalized forms:</para>
+
+ <programlisting> minutely → *-*-* *:*:00
+ hourly → *-*-* *:00:00
+ daily → *-*-* 00:00:00
+ monthly → *-*-01 00:00:00
+ weekly → Mon *-*-* 00:00:00
+ yearly → *-01-01 00:00:00
+ quarterly → *-01,04,07,10-01 00:00:00
+semiannually → *-01,07-01 00:00:00
+ </programlisting>
<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 05:40 UTC → 2003-03-05 05:40:00 UTC
- 2003-03-05 → 2003-03-05 00:00:00
- 03-05 → *-03-05 00:00:00
- hourly → *-*-* *:00:00
- daily → *-*-* 00:00:00
- daily UTC → *-*-* 00:00:00 UTC
- 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>
+<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
+ 12..14:10,20,30 → *-*-* 12..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
+ 05:40:23.4200004/3.1700005 → *-*-* 05:40:23.420000/3.170001
+ 2003-02..04-05 → 2003-02..04-05 00:00:00
+ 2003-03-05 05:40 UTC → 2003-03-05 05:40:00 UTC
+ 2003-03-05 → 2003-03-05 00:00:00
+ 03-05 → *-03-05 00:00:00
+ hourly → *-*-* *:00:00
+ daily → *-*-* 00:00:00
+ daily UTC → *-*-* 00:00:00 UTC
+ monthly → *-*-01 00:00:00
+ weekly → Mon *-*-* 00:00:00
+ weekly Pacific/Auckland → Mon *-*-* 00:00:00 Pacific/Auckland
+ 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>
+ <para>Use the <command>calendar</command> command of
+ <citerefentry><refentrytitle>systemd-analyze</refentrytitle><manvolnum>1</manvolnum></citerefentry> to validate
+ and normalize calendar time specifications for testing purposes. The tool also calculates when a specified
+ calendar event would elapse next.</para>
</refsect1>
<refsect1>
<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>
+ <citerefentry><refentrytitle>systemd.directives</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
+ <citerefentry><refentrytitle>systemd-analyze</refentrytitle><manvolnum>1</manvolnum></citerefentry>
</para>
</refsect1>
projects / thirdparty / systemd.git / blobdiff