<?xml version='1.0'?> <!--*-nxml-*-->
-<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//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/>.
--->
+<!-- SPDX-License-Identifier: LGPL-2.1+ -->
<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>
understood:</para>
<itemizedlist>
- <listitem><para>usec, us</para></listitem>
+ <listitem><para>usec, us, µs</para></listitem>
<listitem><para>msec, ms</para></listitem>
<listitem><para>seconds, second, sec, s</para></listitem>
<listitem><para>minutes, minute, min, m</para></listitem>
1y 12month
55s500ms
300ms20s 5day</programlisting>
+
+ <para>One can use the <command>timespan</command> command of
+ <citerefentry><refentrytitle>systemd-analyze</refentrytitle><manvolnum>1</manvolnum></citerefentry>
+ to normalise a textual time span for testing and validation purposes.</para>
</refsect1>
<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 <literal>UTC</literal> (for the UTC timezone) or is specified to be the locally configured
- timezone. Other timezones than the local and UTC are not supported. 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>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 (e.g. with local timezone
+ it's possible to specify daylight saving time in winter, even though that is not correct). 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>
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 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 → 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
- -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>Examples for valid timestamps and their normalized form (assuming the current time was 2012-11-23
+ 18:15:22 and the timezone was UTC+8, for example <literal>TZ=:Asia/Shanghai</literal>):</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>
<programlisting>2 months 5 days ago</programlisting>
<para>Note that a relative timestamp is also accepted where a timestamp is expected (see above).</para>
+
+ <para>Use the <command>timestamp</command> command of
+ <citerefentry><refentrytitle>systemd-analyze</refentrytitle><manvolnum>1</manvolnum></citerefentry> to
+ validate and normalize timestamps for testing purposes.</para>
</refsect1>
<refsect1>
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 itself and the value plus all multiples of the repetition value
- are matched. Each component may also contain a range of values
- separated by <literal>..</literal>.</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 be suffixed with <literal>/</literal> and a repetition value, which
+ indicates that 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, in which case the expression matches all
+ times starting with the start value, and continuing with all multiples of the repetition value relative
+ to the start value, ending at the end value the latest.</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
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 <literal>UTC</literal>, or
- the local timezone, similar to the supported syntax of timestamps (see above). Non-local timezones except for UTC
- are not supported.</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>
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,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
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,03,04-05 00:00: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
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>
<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 occur 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