Debian Codegraph @

upstream/debian-unstable/man7/systemd.time.7

raw
1 '\" t
2 .TH "SYSTEMD\&.TIME" "7" "" "systemd 261~rc3" "systemd.time"
3 .\" -----------------------------------------------------------------
4 .\" * Define some portability stuff
5 .\" -----------------------------------------------------------------
6 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
7 .\" http://bugs.debian.org/507673
8 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
9 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
10 .ie \n(.g .ds Aq \(aq
11 .el .ds Aq '
12 .\" -----------------------------------------------------------------
13 .\" * set default formatting
14 .\" -----------------------------------------------------------------
15 .\" disable hyphenation
16 .nh
17 .\" disable justification (adjust text to left margin only)
18 .ad l
19 .\" -----------------------------------------------------------------
20 .\" * MAIN CONTENT STARTS HERE *
21 .\" -----------------------------------------------------------------
22 .SH "NAME"
23 systemd.time \- Time and date specifications
24 .SH "DESCRIPTION"
25 .PP
26 In systemd, timestamps, time spans, and calendar events are displayed and may be specified in closely related syntaxes\&.
27 .SH "DISPLAYING TIME SPANS"
28 .PP
29 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\&. Example:
30 .sp
31 .if n \{\
32 .RS 4
33 .\}
34 .nf
35 2h 30min
36 .fi
37 .if n \{\
38 .RE
39 .\}
40 .PP
41 All specified time values are meant to be added up\&. The above hence refers to 150 minutes\&. Display is locale\-independent, only English names for the time units are used\&.
42 .SH "PARSING TIME SPANS"
43 .PP
44 When parsing, systemd will accept the same time span syntax\&. Separating spaces may be omitted\&. The following time units are understood:
45 .sp
46 .RS 4
47 .ie n \{\
48 \h'-04'\(bu\h'+03'\c
49 .\}
50 .el \{\
51 .sp -1
52 .IP \(bu 2.3
53 .\}
54 usec, us, μs
55 .RE
56 .sp
57 .RS 4
58 .ie n \{\
59 \h'-04'\(bu\h'+03'\c
60 .\}
61 .el \{\
62 .sp -1
63 .IP \(bu 2.3
64 .\}
65 msec, ms
66 .RE
67 .sp
68 .RS 4
69 .ie n \{\
70 \h'-04'\(bu\h'+03'\c
71 .\}
72 .el \{\
73 .sp -1
74 .IP \(bu 2.3
75 .\}
76 seconds, second, sec, s
77 .RE
78 .sp
79 .RS 4
80 .ie n \{\
81 \h'-04'\(bu\h'+03'\c
82 .\}
83 .el \{\
84 .sp -1
85 .IP \(bu 2.3
86 .\}
87 minutes, minute, min, m
88 .RE
89 .sp
90 .RS 4
91 .ie n \{\
92 \h'-04'\(bu\h'+03'\c
93 .\}
94 .el \{\
95 .sp -1
96 .IP \(bu 2.3
97 .\}
98 hours, hour, hr, h
99 .RE
100 .sp
101 .RS 4
102 .ie n \{\
103 \h'-04'\(bu\h'+03'\c
104 .\}
105 .el \{\
106 .sp -1
107 .IP \(bu 2.3
108 .\}
109 days, day, d
110 .RE
111 .sp
112 .RS 4
113 .ie n \{\
114 \h'-04'\(bu\h'+03'\c
115 .\}
116 .el \{\
117 .sp -1
118 .IP \(bu 2.3
119 .\}
120 weeks, week, w
121 .RE
122 .sp
123 .RS 4
124 .ie n \{\
125 \h'-04'\(bu\h'+03'\c
126 .\}
127 .el \{\
128 .sp -1
129 .IP \(bu 2.3
130 .\}
131 months, month, M (defined as 30\&.44 days)
132 .RE
133 .sp
134 .RS 4
135 .ie n \{\
136 \h'-04'\(bu\h'+03'\c
137 .\}
138 .el \{\
139 .sp -1
140 .IP \(bu 2.3
141 .\}
142 years, year, y (defined as 365\&.25 days)
143 .RE
144 .PP
145 If no time unit is specified, generally seconds are assumed, but some exceptions exist and are marked as such\&. In a few cases
146 "ns",
147 "nsec"
148 is accepted too, where the granularity of the time span permits this\&. Parsing is generally locale\-independent, non\-English names for the time units are not accepted\&.
149 .PP
150 Examples for valid time span specifications:
151 .sp
152 .if n \{\
153 .RS 4
154 .\}
155 .nf
156 2 h
157 2hours
158 48hr
159 1y 12month
160 55s500ms
161 300ms20s 5day
162 .fi
163 .if n \{\
164 .RE
165 .\}
166 .PP
167 One can use the
168 \fBtimespan\fR
169 command of
170 \fBsystemd-analyze\fR(1)
171 to normalise a textual time span for testing and validation purposes\&.
172 .PP
173 Internally, systemd generally operates with microsecond time granularity, while the default time unit in user\-configurable time spans is usually seconds (see above)\&. This disparity becomes visible when comparing the same settings in the (high\-level) unit file syntax with the matching (more low\-level) D\-Bus properties (which are what
174 \fBsystemctl\fR(1)\*(Aqs
175 \fBshow\fR
176 command displays)\&. The former typically are suffixed with
177 "\&...Sec"
178 to indicate the default unit of seconds, the latter are typically suffixed with
179 "\&...USec"
180 to indicate the underlying low\-level time unit, even if they both encapsulate the very same settings\&.
181 .SH "DISPLAYING TIMESTAMPS"
182 .PP
183 Timestamps refer to specific, unique points in time\&. On display, systemd will format these in the local timezone as follows:
184 .sp
185 .if n \{\
186 .RS 4
187 .\}
188 .nf
189 Fri 2012\-11\-23 23:02:15 CET
190 .fi
191 .if n \{\
192 .RE
193 .\}
194 .PP
195 The weekday is printed in the abbreviated English language form\&. The formatting is locale\-independent\&.
196 .PP
197 In some cases timestamps are shown in the UTC timezone instead of the local timezone, which is indicated via the
198 "UTC"
199 timezone specifier in the output\&.
200 .PP
201 In some cases timestamps are shown with microsecond granularity\&. In this case, the sub\-second remainder is separated by a full stop from the seconds component\&.
202 .SH "PARSING TIMESTAMPS"
203 .PP
204 When parsing, systemd will accept a similar syntax, but some fields can be omitted, and the space between the date and time can be replaced with a
205 "T"
206 (à la the
207 \m[blue]\fBRFC 3339\fR\m[]\&\s-2\u[1]\d\s+2
208 profile of ISO 8601); thus, in CET, the following are all identical:
209 "Fri 2012\-11\-23 23:02:15 CET",
210 "Fri 2012\-11\-23T23:02:15",
211 "2012\-11\-23T23:02:15 CET",
212 "2012\-11\-23 23:02:15"\&.
213 .PP
214 The timezone defaults to the current timezone if not specified explicitly\&. It may be given after a space, like above, in which case it can be:
215 "UTC", an entry in the installed IANA timezone database (e\&.g\&.
216 "CET",
217 "Asia/Tokyo", where the complete list can be obtained with
218 \fBtimedatectl list\-timezones\fR
219 (see
220 \fBtimedatectl\fR(1))), or
221 "\(+-\fI05\fR",
222 "\(+-\fI05\fR\fI30\fR",
223 "\(+-\fI05\fR:\fI30\fR",
224 "Z"\&.
225 .PP
226 It may also be affixed directly to the timestamp, in which case it must correspond to one of the formats defined in the
227 \m[blue]\fBRFC 3339\fR\m[]\&\s-2\u[1]\d\s+2
228 profile of ISO 8601:
229 "\(+-\fI05\fR:\fI30\fR"
230 or
231 "Z"\&. Thus, the following are also identical to the above:
232 "2012\-11\-23T23:02:15+01:00",
233 "2012\-11\-23 22:02:15Z"\&.
234 .PP
235 A timestamp can start with a field containing a weekday, which can be in an abbreviated ("Wed") or non\-abbreviated ("Wednesday") English language form (case does not matter), regardless of the locale\&. However, if a weekday
236 \fIis\fR
237 specified and does not match the date, the timestamp is rejected\&.
238 .PP
239 If the date is omitted, it defaults to today\&. If the time is omitted, it defaults to 00:00:00\&. Fractional seconds can be specified down to 1\(mcs precision\&. The seconds field can also be omitted, defaulting to 0\&.
240 .PP
241 There are special tokens that can be used in place of timestamps:
242 "now"
243 may be used to refer to the current time (or of the invocation of the command that is currently executed)\&.
244 "today",
245 "yesterday", and
246 "tomorrow"
247 refer to 00:00:00 of the current day, the day before, or the next day, respectively\&.
248 .PP
249 Relative times are also accepted: a time span (see above) prefixed with
250 "+"
251 is evaluated to the current time plus the specified time span\&. Correspondingly, a time span that is prefixed with
252 "\-"
253 is evaluated to the current time minus the specified time span\&. Instead of prefixing the time span with
254 "+"
255 or
256 "\-", it may also be suffixed with a space and the word
257 "left"
258 or
259 "ago"\&.
260 .PP
261 Finally, an integer prefixed with
262 "@"
263 is evaluated relative to the UNIX epoch \(en 1970\-01\-01 00:00:00 UTC\&.
264 .PP
265 Examples for valid timestamps and their normalized form (assuming the current time was 2012\-11\-23 18:15:22 and the timezone was UTC+8, for example
266 "TZ=:Asia/Shanghai"):
267 .sp
268 .if n \{\
269 .RS 4
270 .\}
271 .nf
272 Fri 2012\-11\-23 11:12:13 → Fri 2012\-11\-23 11:12:13
273 2012\-11\-23 11:12:13 → Fri 2012\-11\-23 11:12:13
274 2012\-11\-23 11:12:13 UTC → Fri 2012\-11\-23 19:12:13
275 2012\-11\-23T11:12:13Z → Fri 2012\-11\-23 19:12:13
276 2012\-11\-23T11:12+02:00 → Fri 2012\-11\-23 17:12:00
277 2012\-11\-23 → Fri 2012\-11\-23 00:00:00
278 12\-11\-23 → Fri 2012\-11\-23 00:00:00
279 11:12:13 → Fri 2012\-11\-23 11:12:13
280 11:12 → Fri 2012\-11\-23 11:12:00
281 now → Fri 2012\-11\-23 18:15:22
282 today → Fri 2012\-11\-23 00:00:00
283 today UTC → Fri 2012\-11\-23 16:00:00
284 yesterday → Fri 2012\-11\-22 00:00:00
285 tomorrow → Fri 2012\-11\-24 00:00:00
286 tomorrow Pacific/Auckland → Thu 2012\-11\-23 19:00:00
287 +3h30min → Fri 2012\-11\-23 21:45:22
288 \-5s → Fri 2012\-11\-23 18:15:17
289 11min ago → Fri 2012\-11\-23 18:04:22
290 @1395716396 → Tue 2014\-03\-25 03:59:56
291 .fi
292 .if n \{\
293 .RE
294 .\}
295 .PP
296 Note that timestamps displayed by remote systems with a non\-matching timezone are usually not parsable locally, as the timezone component is not understood (unless it happens to be
297 "UTC")\&.
298 .PP
299 Timestamps may also be specified with microsecond granularity\&. The sub\-second remainder is expected separated by a full stop from the seconds component\&. Example:
300 .sp
301 .if n \{\
302 .RS 4
303 .\}
304 .nf
305 2014\-03\-25 03:59:56\&.654563
306 .fi
307 .if n \{\
308 .RE
309 .\}
310 .PP
311 In some cases, systemd will display a relative timestamp (relative to the current time, or the time of invocation of the command) instead of or in addition to an absolute timestamp as described above\&. A relative timestamp is formatted as follows:
312 .sp
313 .if n \{\
314 .RS 4
315 .\}
316 .nf
317 2 months 5 days ago
318 .fi
319 .if n \{\
320 .RE
321 .\}
322 .PP
323 Note that a relative timestamp is also accepted where a timestamp is expected (see above)\&.
324 .PP
325 Use the
326 \fBtimestamp\fR
327 command of
328 \fBsystemd-analyze\fR(1)
329 to validate and normalize timestamps for testing purposes\&.
330 .SH "CALENDAR EVENTS"
331 .PP
332 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:
333 .sp
334 .if n \{\
335 .RS 4
336 .\}
337 .nf
338 Thu,Fri 2012\-*\-1,5 11:12:13
339 .fi
340 .if n \{\
341 .RE
342 .\}
343 .PP
344 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\&.
345 .PP
346 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
347 "\&.\&."
348 refers to a range of continuous weekdays\&.
349 ","
350 and
351 "\&.\&."
352 may be combined freely\&.
353 .PP
354 In the date and time specifications, any component may be specified as
355 "*"
356 in which case any value will match\&. Alternatively, each component can be specified as a list of values separated by commas\&. Values may be suffixed with
357 "/"
358 and a repetition value, which indicates that the value itself and the value plus all multiples of the repetition value are matched\&. Two values separated by
359 "\&.\&."
360 may be used to indicate a range of values; ranges may also be followed with
361 "/"
362 and a repetition value, in which case the expression matches all times starting with the start value, and continuing with all multiples of the repetition value relative to the start value, ending at the end value the latest\&.
363 .PP
364 A date specification may use
365 "~"
366 to indicate the last day in a month\&. For example,
367 "*\-02~03"
368 means "the third last day in February," and
369 "Mon *\-05~07/1"
370 means "the last Monday in May\&."
371 .PP
372 The seconds component may contain decimal fractions both in the value and the repetition\&. All fractions are rounded to 6 decimal places\&.
373 .PP
374 Either time or date specification may be omitted, in which case 00:00:00 and *\-*\-* is implied, respectively\&. If the seconds component is not specified,
375 ":00"
376 is assumed\&.
377 .PP
378 Timezone can be specified as the literal string
379 "UTC", or the local timezone, similar to the supported syntax of timestamps (see above), or the timezone in the IANA timezone database format (also see above)\&.
380 .PP
381 The following special expressions may be used as shorthands for longer normalized forms:
382 .sp
383 .if n \{\
384 .RS 4
385 .\}
386 .nf
387 minutely → *\-*\-*\ \&*:*:00
388 hourly → *\-*\-*\ \&*:00:00
389 daily → *\-*\-*\ \&00:00:00
390 monthly → *\-*\-01\ \&00:00:00
391 weekly → Mon *\-*\-*\ \&00:00:00
392 yearly → *\-01\-01\ \&00:00:00
393 quarterly → *\-01,04,07,10\-01 00:00:00
394 semiannually → *\-01,07\-01 00:00:00
395 .fi
396 .if n \{\
397 .RE
398 .\}
399 .PP
400 Examples for valid timestamps and their normalized form:
401 .sp
402 .if n \{\
403 .RS 4
404 .\}
405 .nf
406 Sat,Thu,Mon\&.\&.Wed,Sat\&.\&.Sun → Mon\&.\&.Thu,Sat,Sun *\-*\-* 00:00:00
407 Mon,Sun 12\-*\-* 2,1:23 → Mon,Sun 2012\-*\-* 01,02:23:00
408 Wed *\-1 → Wed *\-*\-01 00:00:00
409 Wed\&.\&.Wed,Wed *\-1 → Wed *\-*\-01 00:00:00
410 Wed, 17:48 → Wed *\-*\-* 17:48:00
411 Wed\&.\&.Sat,Tue 12\-10\-15 1:2:3 → Tue\&.\&.Sat 2012\-10\-15 01:02:03
412 *\-*\-7 0:0:0 → *\-*\-07 00:00:00
413 10\-15 → *\-10\-15 00:00:00
414 monday *\-12\-* 17:00 → Mon *\-12\-* 17:00:00
415 Mon,Fri *\-*\-3,1,2 *:30:45 → Mon,Fri *\-*\-01,02,03 *:30:45
416 12,14,13,12:20,10,30 → *\-*\-* 12,13,14:10,20,30:00
417 12\&.\&.14:10,20,30 → *\-*\-* 12\&.\&.14:10,20,30:00
418 mon,fri *\-1/2\-1,3 *:30:45 → Mon,Fri *\-01/2\-01,03 *:30:45
419 03\-05 08:05:40 → *\-03\-05 08:05:40
420 08:05:40 → *\-*\-* 08:05:40
421 05:40 → *\-*\-* 05:40:00
422 Sat,Sun 12\-05 08:05:40 → Sat,Sun *\-12\-05 08:05:40
423 Sat,Sun 08:05:40 → Sat,Sun *\-*\-* 08:05:40
424 2003\-03\-05 05:40 → 2003\-03\-05 05:40:00
425 05:40:23\&.4200004/3\&.1700005 → *\-*\-* 05:40:23\&.420000/3\&.170001
426 2003\-02\&.\&.04\-05 → 2003\-02\&.\&.04\-05 00:00:00
427 2003\-03\-05 05:40 UTC → 2003\-03\-05 05:40:00 UTC
428 2003\-03\-05 → 2003\-03\-05 00:00:00
429 03\-05 → *\-03\-05 00:00:00
430 hourly → *\-*\-* *:00:00
431 daily → *\-*\-* 00:00:00
432 daily UTC → *\-*\-* 00:00:00 UTC
433 monthly → *\-*\-01 00:00:00
434 weekly → Mon *\-*\-* 00:00:00
435 weekly Pacific/Auckland → Mon *\-*\-* 00:00:00 Pacific/Auckland
436 yearly → *\-01\-01 00:00:00
437 annually → *\-01\-01 00:00:00
438 *:2/3 → *\-*\-* *:02/3:00
439 .fi
440 .if n \{\
441 .RE
442 .\}
443 .PP
444 Calendar events are used by timer units, see
445 \fBsystemd.timer\fR(5)
446 for details\&.
447 .PP
448 Use the
449 \fBcalendar\fR
450 command of
451 \fBsystemd-analyze\fR(1)
452 to validate and normalize calendar time specifications for testing purposes\&. The tool also calculates when a specified calendar event would occur next\&.
453 .SH "SEE ALSO"
454 .PP
455 \fBsystemd\fR(1), \fBjournalctl\fR(1), \fBsystemd.timer\fR(5), \fBsystemd.unit\fR(5), \fBsystemd.directives\fR(7), \fBsystemd-analyze\fR(1)
456 .SH "NOTES"
457 .IP " 1." 4
458 RFC 3339
459 .RS 4
460 \%https://tools.ietf.org/html/rfc3339
461 .RE