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, timespans, and calendar
54 events are displayed and may be specified in closely
55 related syntaxes.</para>
59 <title>Displaying Timespans</title>
61 <para>Timespans refer to time durations. On display
62 systemd will present timespans 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 Timespans</title>
75 <para>When parsing systemd will accept the same
76 timespan 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 timespan allows for this.</para>
97 <para>Examples for valid timespan 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 week day 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 week day specification is optional,
127 but when the week day 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 doesn't 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 week day
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 timespan (see above) that is
155 prefixed with <literal>+</literal> is evaluated to the
156 current time plus the specified
157 timespan. Correspondingly a timespan that is prefix
158 with <literal>-</literal> is evaluated to the current
159 time minus the specified timespan. Instead of
160 prefixing the timespan 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 week day while
186 parsing only accepts english week day 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 week day names, either in the abbreviated
216 (Wed) or non-abbreviated (Wednesday) form (case does
217 not matter), separated by commas. Specifying two week
218 days separated by "-" refers to a range of continuous
219 week days. "," and "-" may be combined freely.</para>
221 <para>In the date and time specifications any
222 component may be specified as "*" in which case any
223 value will match. Alternatively, each component can be
224 specified as list of values separated by
225 commas. Values may also be suffixed with "/" and a
226 repetition value, which indicates that the value and
227 all values plus multiples of the repetition value are
230 <para>Either time or date specification may be
231 omitted, in which case the current day and 00:00:00 is
232 implied, respectively. If the second component is not
233 specified ":00" is assumed.</para>
235 <para>Timezone names may not be specified.</para>
237 <para>The special expressions
238 <literal>hourly</literal>, <literal>daily</literal>,
239 <literal>monthly</literal> and <literal>weekly</literal>
240 may be used as calendar events which refer to
241 <literal>*-*-* *:00:00</literal>, <literal>*-*-*
242 00:00:00</literal>, <literal>*-*-01 00:00:00</literal> and
243 <literal>Mon *-*-* 00:00:00</literal>,
246 <para>Examples for valid timestamps and their
247 normalized form:</para>
249 <programlisting> Sat,Thu,Mon-Wed,Sat-Sun → Mon-Thu,Sat,Sun *-*-* 00:00:00
250 Mon,Sun 12-*-* 2,1:23 → Mon,Sun 2012-*-* 01,02:23:00
251 Wed *-1 → Wed *-*-01 00:00:00
252 Wed-Wed,Wed *-1 → Wed *-*-01 00:00:00
253 Wed, 17:48 → Wed *-*-* 17:48:00
254 Wed-Sat,Tue 12-10-15 1:2:3 → Tue-Sat 2012-10-15 01:02:03
255 *-*-7 0:0:0 → *-*-07 00:00:00
256 10-15 → *-10-15 00:00:00
257 monday *-12-* 17:00 → Mon *-12-* 17:00:00
258 Mon,Fri *-*-3,1,2 *:30:45 → Mon,Fri *-*-01,02,03 *:30:45
259 12,14,13,12:20,10,30 → *-*-* 12,13,14:10,20,30:00
260 mon,fri *-1/2-1,3 *:30:45 → Mon,Fri *-01/2-01,03 *:30:45
261 03-05 08:05:40 → *-03-05 08:05:40
262 08:05:40 → *-*-* 08:05:40
263 05:40 → *-*-* 05:40:00
264 Sat,Sun 12-05 08:05:40 → Sat,Sun *-12-05 08:05:40
265 Sat,Sun 08:05:40 → Sat,Sun *-*-* 08:05:40
266 2003-03-05 05:40 → 2003-03-05 05:40:00
267 2003-03-05 → 2003-03-05 00:00:00
268 03-05 → *-03-05 00:00:00
269 hourly → *-*-* *:00:00
270 daily → *-*-* 00:00:00
271 monthly → *-*-01 00:00:00
272 weekly → Mon *-*-* 00:00:00
273 *:2/3 → *-*-* *:02/3:00</programlisting>
275 <para>Calendar events are used by timer units, see
276 <citerefentry><refentrytitle>systemd.timer</refentrytitle><manvolnum>5</manvolnum></citerefentry>
282 <title>See Also</title>
284 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
285 <citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
286 <citerefentry><refentrytitle>systemd.timer</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
287 <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
288 <citerefentry><refentrytitle>systemd.directives</refentrytitle><manvolnum>7</manvolnum></citerefentry>