2012-11-23 23:24:14 +00:00
|
|
|
|
<?xml version='1.0'?> <!--*-nxml-*-->
|
|
|
|
|
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
|
2015-06-18 17:47:44 +00:00
|
|
|
|
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
|
2012-11-23 23:24:14 +00:00
|
|
|
|
|
|
|
|
|
<!--
|
|
|
|
|
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">
|
|
|
|
|
|
2015-02-04 02:14:13 +00:00
|
|
|
|
<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
|
2012-11-23 23:24:14 +00:00
|
|
|
|
2hours
|
|
|
|
|
48hr
|
|
|
|
|
1y 12month
|
|
|
|
|
55s500ms
|
|
|
|
|
300ms20s 5day</programlisting>
|
2015-02-04 02:14:13 +00:00
|
|
|
|
</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
|
2015-06-26 16:02:00 +00:00
|
|
|
|
the current date or 00:00:00, respectively, is assumed. The seconds
|
2015-02-04 02:14:13 +00:00
|
|
|
|
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 23:24:14 +00:00
|
|
|
|
2012-11-23 11:12:13 → Fri 2012-11-23 11:12:13
|
2015-02-04 02:14:13 +00:00
|
|
|
|
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 23:24:14 +00:00
|
|
|
|
|
|
|
|
|
<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
|
2015-02-04 02:14:13 +00:00
|
|
|
|
Wed *-1 → Wed *-*-01 00:00:00
|
|
|
|
|
Wed-Wed,Wed *-1 → Wed *-*-01 00:00:00
|
|
|
|
|
Wed, 17:48 → Wed *-*-* 17:48:00
|
2012-11-23 23:24:14 +00:00
|
|
|
|
Wed-Sat,Tue 12-10-15 1:2:3 → Tue-Sat 2012-10-15 01:02:03
|
2015-02-04 02:14:13 +00:00
|
|
|
|
*-*-7 0:0:0 → *-*-07 00:00:00
|
|
|
|
|
10-15 → *-10-15 00:00:00
|
2012-11-23 23:24:14 +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
|
2015-02-04 02:14:13 +00:00
|
|
|
|
03-05 08:05:40 → *-03-05 08:05:40
|
|
|
|
|
08:05:40 → *-*-* 08:05:40
|
|
|
|
|
05:40 → *-*-* 05:40:00
|
2012-11-23 23:24:14 +00:00
|
|
|
|
Sat,Sun 12-05 08:05:40 → Sat,Sun *-12-05 08:05:40
|
2015-02-04 02:14:13 +00:00
|
|
|
|
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>
|
2012-11-23 23:24:14 +00:00
|
|
|
|
|
|
|
|
|
</refentry>
|