1 <?xml version='
1.0'
?> <!--*-nxml-*-->
2 <!DOCTYPE refentry PUBLIC
"-//OASIS//DTD DocBook XML V4.2//EN"
3 "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
6 This file is part of systemd.
8 Copyright 2010 Lennart Poettering
10 systemd is free software; you can redistribute it and/or modify it
11 under the terms of the GNU Lesser General Public License as published by
12 the Free Software Foundation; either version 2.1 of the License, or
13 (at your option) any later version.
15 systemd is distributed in the hope that it will be useful, but
16 WITHOUT ANY WARRANTY; without even the implied warranty of
17 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
18 Lesser General Public License for more details.
20 You should have received a copy of the GNU Lesser General Public License
21 along with systemd; If not, see <http://www.gnu.org/licenses/>.
24 <refentry id=
"systemd.time">
27 <title>systemd.time
</title>
28 <productname>systemd
</productname>
32 <contrib>Developer
</contrib>
33 <firstname>Lennart
</firstname>
34 <surname>Poettering
</surname>
35 <email>lennart@poettering.net
</email>
41 <refentrytitle>systemd.time
</refentrytitle>
42 <manvolnum>7</manvolnum>
46 <refname>systemd.time
</refname>
47 <refpurpose>Time and date specifications
</refpurpose>
51 <title>Description
</title>
53 <para>In systemd, timestamps, time spans, and calendar events are
54 displayed and may be specified in closely related syntaxes.
</para>
58 <title>Displaying Time Spans
</title>
60 <para>Time spans refer to time durations. On display, systemd will
61 present time spans as a space-separated series of time values each
62 suffixed by a time unit.
</para>
64 <programlisting>2h
30min
</programlisting>
66 <para>All specified time values are meant to be added up. The
67 above hence refers to
150 minutes.
</para>
71 <title>Parsing Time Spans
</title>
73 <para>When parsing, systemd will accept the same time span syntax.
74 Separating spaces may be omitted. The following time units are
78 <listitem><para>usec, us
</para></listitem>
79 <listitem><para>msec, ms
</para></listitem>
80 <listitem><para>seconds, second, sec, s
</para></listitem>
81 <listitem><para>minutes, minute, min, m
</para></listitem>
82 <listitem><para>hours, hour, hr, h
</para></listitem>
83 <listitem><para>days, day, d
</para></listitem>
84 <listitem><para>weeks, week, w
</para></listitem>
85 <listitem><para>months, month
</para></listitem>
86 <listitem><para>years, year, y
</para></listitem>
89 <para>If no time unit is specified, generally seconds are assumed,
90 but some exceptions exist and are marked as such. In a few cases
91 <literal>ns
</literal>,
<literal>nsec
</literal> is accepted too,
92 where the granularity of the time span allows for this.
</para>
94 <para>Examples for valid time span specifications:
</para>
101 300ms20s
5day
</programlisting>
105 <title>Displaying Timestamps
</title>
107 <para>Timestamps refer to specific, unique points in time. On
108 display, systemd will format these in the local timezone as
111 <programlisting>Fri
2012-
11-
23 23:
02:
15 CET
</programlisting>
113 <para>The weekday is printed according to the locale choice of the
118 <title>Parsing Timestamps
</title>
120 <para>When parsing, systemd will accept a similar syntax, but
121 expects no timezone specification, unless it is given as the
122 literal string
"UTC". In this case, the time is considered in UTC,
123 otherwise in the local timezone. The weekday specification is
124 optional, but when the weekday is specified, it must either be in
125 the abbreviated (
<literal>Wed
</literal>) or non-abbreviated
126 (
<literal>Wednesday
</literal>) English language form (case does
127 not matter), and is not subject to the locale choice of the user.
128 Either the date, or the time part may be omitted, in which case
129 the current date or
00:
00:
00, respectively, is assumed. The seconds
130 component of the time may also be omitted, in which case
":00" is
131 assumed. Year numbers may be specified in full or may be
132 abbreviated (omitting the century).
</para>
134 <para>A timestamp is considered invalid if a weekday is specified
135 and the date does not actually match the specified day of the
138 <para>When parsing, systemd will also accept a few special
139 placeholders instead of timestamps:
<literal>now
</literal> may be
140 used to refer to the current time (or of the invocation of the
141 command that is currently executed).
<literal>today
</literal>,
142 <literal>yesterday
</literal>, and
<literal>tomorrow
</literal> refer to
143 00:
00:
00 of the current day, the day before, or the next day,
146 <para>When parsing, systemd will also accept relative time
147 specifications. A time span (see above) that is prefixed with
148 <literal>+
</literal> is evaluated to the current time plus the
149 specified time span. Correspondingly, a time span that is prefixed
150 with
<literal>-
</literal> is evaluated to the current time minus
151 the specified time span. Instead of prefixing the time span with
152 <literal>+
</literal> or
<literal>-
</literal>, it may also be
153 suffixed with a space and the word
<literal>left
</literal> or
154 <literal>ago
</literal>.
</para>
156 <para>Finally, a timespan prefixed with
<literal>@
</literal> is
157 evaluated relative to the UNIX time epoch
1st Jan,
1970,
160 <para>Examples for valid timestamps and their normalized form
161 (assuming the current time was
2012-
11-
23 18:
15:
22 and the timezone
162 was UTC+
8, for example TZ=Asia/Shanghai):
</para>
164 <programlisting>Fri
2012-
11-
23 11:
12:
13 → Fri
2012-
11-
23 11:
12:
13
165 2012-
11-
23 11:
12:
13 → Fri
2012-
11-
23 11:
12:
13
166 2012-
11-
23 11:
12:
13 UTC → Fri
2012-
11-
23 19:
12:
13
167 2012-
11-
23 → Fri
2012-
11-
23 00:
00:
00
168 12-
11-
23 → Fri
2012-
11-
23 00:
00:
00
169 11:
12:
13 → Fri
2012-
11-
23 11:
12:
13
170 11:
12:
13.9900009 → Fri
2012-
11-
23 11:
12:
13
171 format_timestamp_us: Fri
2012-
11-
23 11:
12:
13.990000
172 11:
12 → Fri
2012-
11-
23 11:
12:
00
173 now → Fri
2012-
11-
23 18:
15:
22
174 today → Fri
2012-
11-
23 00:
00:
00
175 today UTC → Fri
2012-
11-
23 16:
00:
00
176 yesterday → Fri
2012-
11-
22 00:
00:
00
177 tomorrow → Fri
2012-
11-
24 00:
00:
00
178 +
3h30min → Fri
2012-
11-
23 21:
45:
22
179 +
3h30min UTC → -EINVAL
180 -
5s → Fri
2012-
11-
23 18:
15:
17
181 11min ago → Fri
2012-
11-
23 18:
04:
22
182 11min ago UTC → -EINVAL
183 @
1395716396 → Tue
2014-
03-
25 03:
59:
56</programlisting>
185 <para>Note that timestamps printed by systemd will not be parsed
186 correctly by systemd, as the timezone specification is not
187 accepted, and printing timestamps is subject to locale settings
188 for the weekday, while parsing only accepts English weekday
191 <para>In some cases, systemd will display a relative timestamp
192 (relative to the current time, or the time of invocation of the
193 command) instead or in addition to an absolute timestamp as
194 described above. A relative timestamp is formatted as
197 <para>2 months
5 days ago
</para>
199 <para>Note that any relative timestamp will also parse correctly
200 where a timestamp is expected. (see above)
</para>
204 <title>Calendar Events
</title>
206 <para>Calendar events may be used to refer to one or more points
207 in time in a single expression. They form a superset of the
208 absolute timestamps explained above:
</para>
210 <programlisting>Thu,Fri
2012-*-
1,
5 11:
12:
13</programlisting>
212 <para>The above refers to
11:
12:
13 of the first or fifth day of
213 any month of the year
2012, but only if that day is a Thursday or
216 <para>The weekday specification is optional. If specified, it
217 should consist of one or more English language weekday names,
218 either in the abbreviated (Wed) or non-abbreviated (Wednesday)
219 form (case does not matter), separated by commas. Specifying two
220 weekdays separated by
<literal>-
</literal> refers to a range of
221 continuous weekdays.
<literal>,
</literal> and
<literal>-
</literal>
222 may be combined freely.
</para>
224 <para>In the date and time specifications, any component may be
225 specified as
<literal>*
</literal> in which case any value will
226 match. Alternatively, each component can be specified as a list of
227 values separated by commas. Values may also be suffixed with
228 <literal>/
</literal> and a repetition value, which indicates that
229 the value and all values plus multiples of the repetition value
232 <para>Either time or date specification may be omitted, in which
233 case the current day and
00:
00:
00 is implied, respectively. If the
234 second component is not specified,
<literal>:
00</literal> is
237 <para>A timezone specification is not expected, unless it is given
238 as the literal string
"UTC", similarly to timestamps.
</para>
240 <para>The special expressions
241 <literal>minutely
</literal>,
242 <literal>hourly
</literal>,
<literal>daily
</literal>,
243 <literal>monthly
</literal>,
<literal>weekly
</literal>,
244 <literal>yearly
</literal>,
245 <literal>quarterly
</literal>,
246 <literal>semiannually
</literal> may be used as
247 calendar events which refer to
248 <literal>*-*-* *:*:
00</literal>,
249 <literal>*-*-* *:
00:
00</literal>,
250 <literal>*-*-*
00:
00:
00</literal>,
251 <literal>*-*-
01 00:
00:
00</literal>,
252 <literal>Mon *-*-*
00:
00:
00</literal>,
253 <literal>*-
01-
01 00:
00:
00</literal>,
254 <literal>*-
01,
04,
07,
10-
01 00:
00:
00</literal> and
255 <literal>*-
01,
07-
01 00:
00:
00</literal>, respectively.
258 <para>Examples for valid timestamps and their
259 normalized form:
</para>
261 <programlisting> Sat,Thu,Mon-Wed,Sat-Sun → Mon-Thu,Sat,Sun *-*-*
00:
00:
00
262 Mon,Sun
12-*-*
2,
1:
23 → Mon,Sun
2012-*-*
01,
02:
23:
00
263 Wed *-
1 → Wed *-*-
01 00:
00:
00
264 Wed-Wed,Wed *-
1 → Wed *-*-
01 00:
00:
00
265 Wed,
17:
48 → Wed *-*-*
17:
48:
00
266 Wed-Sat,Tue
12-
10-
15 1:
2:
3 → Tue-Sat
2012-
10-
15 01:
02:
03
267 *-*-
7 0:
0:
0 → *-*-
07 00:
00:
00
268 10-
15 → *-
10-
15 00:
00:
00
269 monday *-
12-*
17:
00 → Mon *-
12-*
17:
00:
00
270 Mon,Fri *-*-
3,
1,
2 *:
30:
45 → Mon,Fri *-*-
01,
02,
03 *:
30:
45
271 12,
14,
13,
12:
20,
10,
30 → *-*-*
12,
13,
14:
10,
20,
30:
00
272 mon,fri *-
1/
2-
1,
3 *:
30:
45 → Mon,Fri *-
01/
2-
01,
03 *:
30:
45
273 03-
05 08:
05:
40 → *-
03-
05 08:
05:
40
274 08:
05:
40 → *-*-*
08:
05:
40
275 05:
40 → *-*-*
05:
40:
00
276 Sat,Sun
12-
05 08:
05:
40 → Sat,Sun *-
12-
05 08:
05:
40
277 Sat,Sun
08:
05:
40 → Sat,Sun *-*-*
08:
05:
40
278 2003-
03-
05 05:
40 →
2003-
03-
05 05:
40:
00
279 2003-
03-
05 05:
40 UTC →
2003-
03-
05 05:
40:
00 UTC
280 2003-
03-
05 →
2003-
03-
05 00:
00:
00
281 03-
05 → *-
03-
05 00:
00:
00
282 hourly → *-*-* *:
00:
00
283 daily → *-*-*
00:
00:
00
284 daily UTC → *-*-*
00:
00:
00 UTC
285 monthly → *-*-
01 00:
00:
00
286 weekly → Mon *-*-*
00:
00:
00
287 yearly → *-
01-
01 00:
00:
00
288 annually → *-
01-
01 00:
00:
00
289 *:
2/
3 → *-*-* *:
02/
3:
00</programlisting>
291 <para>Calendar events are used by timer units, see
292 <citerefentry><refentrytitle>systemd.timer
</refentrytitle><manvolnum>5</manvolnum></citerefentry>
298 <title>See Also
</title>
300 <citerefentry><refentrytitle>systemd
</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
301 <citerefentry><refentrytitle>journalctl
</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
302 <citerefentry><refentrytitle>systemd.timer
</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
303 <citerefentry><refentrytitle>systemd.unit
</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
304 <citerefentry><refentrytitle>systemd.directives
</refentrytitle><manvolnum>7</manvolnum></citerefentry>