chiark / gitweb /
mount/service: drop FsckPassNo support
[elogind.git] / man / systemd.time.xml
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">
4
5 <!--
6   This file is part of systemd.
7
8   Copyright 2010 Lennart Poettering
9
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.
14
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.
19
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/>.
22 -->
23
24 <refentry id="systemd.time">
25
26         <refentryinfo>
27                 <title>systemd.time</title>
28                 <productname>systemd</productname>
29
30                 <authorgroup>
31                         <author>
32                                 <contrib>Developer</contrib>
33                                 <firstname>Lennart</firstname>
34                                 <surname>Poettering</surname>
35                                 <email>lennart@poettering.net</email>
36                         </author>
37                 </authorgroup>
38         </refentryinfo>
39
40         <refmeta>
41                 <refentrytitle>systemd.time</refentrytitle>
42                 <manvolnum>7</manvolnum>
43         </refmeta>
44
45         <refnamediv>
46                 <refname>systemd.time</refname>
47                 <refpurpose>Time and date specifications</refpurpose>
48         </refnamediv>
49
50         <refsect1>
51                 <title>Description</title>
52
53                 <para>In systemd, timestamps, time spans, and calendar
54                 events are displayed and may be specified in closely
55                 related syntaxes.</para>
56         </refsect1>
57
58         <refsect1>
59                 <title>Displaying Time Spans</title>
60
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
64                 unit.</para>
65
66                 <programlisting>2h 30min</programlisting>
67
68                 <para>All specified time values are meant to be added
69                 up. The above hence refers to 150 minutes.</para>
70         </refsect1>
71
72         <refsect1>
73                 <title>Parsing Time Spans</title>
74
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>
78
79                 <itemizedlist>
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>
89                 </itemizedlist>
90
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>
96
97                 <para>Examples for valid time span specifications:</para>
98
99                 <programlisting>2 h
100 2hours
101 48hr
102 1y 12month
103 55s500ms
104 300ms20s 5day</programlisting>
105         </refsect1>
106
107         <refsect1>
108                 <title>Displaying Timestamps</title>
109
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>
113
114                 <programlisting>Fri 2012-11-23 23:02:15 CET</programlisting>
115
116                 <para>The weekday is printed according to the locale
117                 choice of the user.</para>
118         </refsect1>
119
120         <refsect1>
121                 <title>Parsing Timestamps</title>
122
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
137                 century).</para>
138
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>
142
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,
151                 respectively.</para>
152
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>
163
164                 <para>Examples for valid timestamps and their
165                 normalized form (assuming the current time was
166                 2012-11-23 18:15:22):</para>
167
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>
181
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>
187
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>
193
194                 <para>2 months 5 days ago</para>
195
196                 <para>Note that any relative timestamp will also parse
197                 correctly where a timestamp is expected. (see above)</para>
198         </refsect1>
199
200         <refsect1>
201                 <title>Calendar Events</title>
202
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>
206
207                 <programlisting>Thu,Fri 2012-*-1,5 11:12:13</programlisting>
208
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>
212
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>
221
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>
230
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>
235
236                 <para>Timezone names may not be specified.</para>
237
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>,
245                 respectively.</para>
246
247                 <para>Examples for valid timestamps and their
248                 normalized form:</para>
249
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>
275
276                   <para>Calendar events are used by timer units, see
277                   <citerefentry><refentrytitle>systemd.timer</refentrytitle><manvolnum>5</manvolnum></citerefentry>
278                   for details.</para>
279
280         </refsect1>
281
282         <refsect1>
283                   <title>See Also</title>
284                   <para>
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>
290                   </para>
291         </refsect1>
292
293 </refentry>