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
54 events are displayed and may be specified in closely
55 related syntaxes.
</para>
59 <title>Displaying Time Spans
</title>
61 <para>Time spans refer to time durations. On display,
62 systemd will present time spans as a space-separated
63 series of time values each suffixed by a time
66 <programlisting>2h
30min
</programlisting>
68 <para>All specified time values are meant to be added
69 up. The above hence refers to
150 minutes.
</para>
73 <title>Parsing Time Spans
</title>
75 <para>When parsing, systemd will accept the same
76 time span syntax. Separating spaces may be omitted. The
77 following time units are understood:
</para>
80 <listitem><para>usec, us
</para></listitem>
81 <listitem><para>msec, ms
</para></listitem>
82 <listitem><para>seconds, second, sec, s
</para></listitem>
83 <listitem><para>minutes, minute, min, m
</para></listitem>
84 <listitem><para>hours, hour, hr, h
</para></listitem>
85 <listitem><para>days, day, d
</para></listitem>
86 <listitem><para>weeks, week, w
</para></listitem>
87 <listitem><para>months, month
</para></listitem>
88 <listitem><para>years, year, y
</para></listitem>
91 <para>If no time unit is specified, generally seconds
92 are assumed, but some exceptions exist and are marked
93 as such. In a few cases
<literal>ns
</literal>,
94 <literal>nsec
</literal> is accepted too, where the
95 granularity of the time span allows for this.
</para>
97 <para>Examples for valid time span specifications:
</para>
104 300ms20s
5day
</programlisting>
108 <title>Displaying Timestamps
</title>
110 <para>Timestamps refer to specific, unique points in
111 time. On display, systemd will format these in the
112 local timezone as follows:
</para>
114 <programlisting>Fri
2012-
11-
23 23:
02:
15 CET
</programlisting>
116 <para>The weekday is printed according to the locale
117 choice of the user.
</para>
121 <title>Parsing Timestamps
</title>
123 <para>When parsing systemd will accept a similar
124 timestamp syntax, but excluding any timezone
125 specification (this limitation might be removed
126 eventually). The weekday specification is optional,
127 but when the weekday is specified it must either be
128 in the abbreviated (
<literal>Wed
</literal>) or
129 non-abbreviated (
<literal>Wednesday
</literal>) English
130 language form (case does not matter), and is not
131 subject to the locale choice of the user. Either the
132 date, or the time part may be omitted, in which case
133 the current date or
00:
00:
00, resp., is assumed. The
134 seconds component of the time may also be omitted, in
135 which case
":00" is assumed. Year numbers may be
136 specified in full or may be abbreviated (omitting the
139 <para>A timestamp is considered invalid if a weekday
140 is specified and the date does not actually match the
141 specified day of the week.
</para>
143 <para>When parsing, systemd will also accept a few
144 special placeholders instead of timestamps:
145 <literal>now
</literal> may be used to refer to the
146 current time (or of the invocation of the command
147 that is currently executed).
<literal>today
</literal>,
148 <literal>yesterday
</literal>,
149 <literal>tomorrow
</literal> refer to
00:
00:
00 of the
150 current day, the day before or the next day,
153 <para>When parsing, systemd will also accept relative
154 time specifications. A time span (see above) that is
155 prefixed with
<literal>+
</literal> is evaluated to the
156 current time plus the specified
157 time span. Correspondingly, a time span that is prefixed
158 with
<literal>-
</literal> is evaluated to the current
159 time minus the specified time span. Instead of
160 prefixing the time span with
<literal>-
</literal>, it
161 may also be suffixed with a space and the word
162 <literal>ago
</literal>.
</para>
164 <para>Examples for valid timestamps and their
165 normalized form (assuming the current time was
166 2012-
11-
23 18:
15:
22):
</para>
168 <programlisting>Fri
2012-
11-
23 11:
12:
13 → Fri
2012-
11-
23 11:
12:
13
169 2012-
11-
23 11:
12:
13 → Fri
2012-
11-
23 11:
12:
13
170 2012-
11-
23 → Fri
2012-
11-
23 00:
00:
00
171 12-
11-
23 → Fri
2012-
11-
23 00:
00:
00
172 11:
12:
13 → Fri
2012-
11-
23 11:
12:
13
173 11:
12 → Fri
2012-
11-
23 11:
12:
00
174 now → Fri
2012-
11-
23 18:
15:
22
175 today → Fri
2012-
11-
23 00:
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 -
5s → Fri
2012-
11-
23 18:
15:
17
180 11min ago → Fri
2012-
11-
23 18:
04:
22</programlisting>
182 <para>Note that timestamps printed by systemd will not
183 be parsed correctly by systemd, as the timezone
184 specification is not accepted, and printing timestamps
185 is subject to locale settings for the weekday while
186 parsing only accepts English weekday names.
</para>
188 <para>In some cases, systemd will display a relative
189 timestamp (relative to the current time, or the time
190 of invocation of the command) instead or in addition
191 to an absolute timestamp as described above. A
192 relative timestamp is formatted as follows:
</para>
194 <para>2 months
5 days ago
</para>
196 <para>Note that any relative timestamp will also parse
197 correctly where a timestamp is expected. (see above)
</para>
201 <title>Calendar Events
</title>
203 <para>Calendar events may be used to refer to one or
204 more points in time in a single expression. They form
205 a superset of the absolute timestamps explained above:
</para>
207 <programlisting>Thu,Fri
2012-*-
1,
5 11:
12:
13</programlisting>
209 <para>The above refers to
11:
12:
13 of the first or
210 fifth day of any month of the year
2012, given that it
211 is a Thursday or Friday.
</para>
213 <para>The weekday specification is optional. If
214 specified, it should consist of one or more English
215 language weekday names, either in the abbreviated
216 (Wed) or non-abbreviated (Wednesday) form (case does
217 not matter), separated by commas. Specifying two
218 weekdays separated by
<literal>-
</literal> refers to a
219 range of continuous weekdays.
<literal>,
</literal> and
220 <literal>-
</literal> may be combined freely.
</para>
222 <para>In the date and time specifications, any
223 component may be specified as
<literal>*
</literal> in
224 which case any value will match. Alternatively, each
225 component can be specified as list of values separated
226 by commas. Values may also be suffixed with
227 <literal>/
</literal> and a repetition value, which
228 indicates that the value and all values plus multiples
229 of the repetition value are matched.
</para>
231 <para>Either time or date specification may be
232 omitted, in which case the current day and
00:
00:
00 is
233 implied, respectively. If the second component is not
234 specified,
<literal>:
00</literal> is assumed.
</para>
236 <para>Timezone names may not be specified.
</para>
238 <para>The special expressions
239 <literal>hourly
</literal>,
<literal>daily
</literal>,
240 <literal>monthly
</literal> and
<literal>weekly
</literal>
241 may be used as calendar events which refer to
242 <literal>*-*-* *:
00:
00</literal>,
<literal>*-*-*
243 00:
00:
00</literal>,
<literal>*-*-
01 00:
00:
00</literal> and
244 <literal>Mon *-*-*
00:
00:
00</literal>,
247 <para>Examples for valid timestamps and their
248 normalized form:
</para>
250 <programlisting> Sat,Thu,Mon-Wed,Sat-Sun → Mon-Thu,Sat,Sun *-*-*
00:
00:
00
251 Mon,Sun
12-*-*
2,
1:
23 → Mon,Sun
2012-*-*
01,
02:
23:
00
252 Wed *-
1 → Wed *-*-
01 00:
00:
00
253 Wed-Wed,Wed *-
1 → Wed *-*-
01 00:
00:
00
254 Wed,
17:
48 → Wed *-*-*
17:
48:
00
255 Wed-Sat,Tue
12-
10-
15 1:
2:
3 → Tue-Sat
2012-
10-
15 01:
02:
03
256 *-*-
7 0:
0:
0 → *-*-
07 00:
00:
00
257 10-
15 → *-
10-
15 00:
00:
00
258 monday *-
12-*
17:
00 → Mon *-
12-*
17:
00:
00
259 Mon,Fri *-*-
3,
1,
2 *:
30:
45 → Mon,Fri *-*-
01,
02,
03 *:
30:
45
260 12,
14,
13,
12:
20,
10,
30 → *-*-*
12,
13,
14:
10,
20,
30:
00
261 mon,fri *-
1/
2-
1,
3 *:
30:
45 → Mon,Fri *-
01/
2-
01,
03 *:
30:
45
262 03-
05 08:
05:
40 → *-
03-
05 08:
05:
40
263 08:
05:
40 → *-*-*
08:
05:
40
264 05:
40 → *-*-*
05:
40:
00
265 Sat,Sun
12-
05 08:
05:
40 → Sat,Sun *-
12-
05 08:
05:
40
266 Sat,Sun
08:
05:
40 → Sat,Sun *-*-*
08:
05:
40
267 2003-
03-
05 05:
40 →
2003-
03-
05 05:
40:
00
268 2003-
03-
05 →
2003-
03-
05 00:
00:
00
269 03-
05 → *-
03-
05 00:
00:
00
270 hourly → *-*-* *:
00:
00
271 daily → *-*-*
00:
00:
00
272 monthly → *-*-
01 00:
00:
00
273 weekly → Mon *-*-*
00:
00:
00
274 *:
2/
3 → *-*-* *:
02/
3:
00</programlisting>
276 <para>Calendar events are used by timer units, see
277 <citerefentry><refentrytitle>systemd.timer
</refentrytitle><manvolnum>5</manvolnum></citerefentry>
283 <title>See Also
</title>
285 <citerefentry><refentrytitle>systemd
</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
286 <citerefentry><refentrytitle>journalctl
</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
287 <citerefentry><refentrytitle>systemd.timer
</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
288 <citerefentry><refentrytitle>systemd.unit
</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
289 <citerefentry><refentrytitle>systemd.directives
</refentrytitle><manvolnum>7</manvolnum></citerefentry>