1SYSTEMD.TIME(7) systemd.time SYSTEMD.TIME(7)
2
6 systemd.time - Time and date specifications
7
9 In systemd, timestamps, time spans, and calendar events are displayed
10 and may be specified in closely related syntaxes.
11
13 Time spans refer to time durations. On display, systemd will present
14 time spans as a space-separated series of time values each suffixed by
15 a time unit. Example:
16 2h 30min
18 All specified time values are meant to be added up. The above hence
20 refers to 150 minutes. Display is locale-independent, only English
21 names for the time units are used.
22
24 When parsing, systemd will accept the same time span syntax. Separating
25 spaces may be omitted. The following time units are understood:
26 · usec, us, µs
28 · msec, ms
30 · seconds, second, sec, s
32 · minutes, minute, min, m
34 · hours, hour, hr, h
36 · days, day, d
38 · weeks, week, w
40 · months, month, M (defined as 30.44 days)
42 · years, year, y (defined as 365.25 days)
44 If no time unit is specified, generally seconds are assumed, but some
46 exceptions exist and are marked as such. In a few cases "ns", "nsec" is
47 accepted too, where the granularity of the time span permits this.
48 Parsing is generally locale-independent, non-English names for the time
49 units are not accepted.
50 Examples for valid time span specifications:
52 2 h
54 2hours
55 48hr
56 1y 12month
57 55s500ms
58 300ms20s 5day
59 One can use the timespan command of systemd-analyze(1) to normalise a
61 textual time span for testing and validation purposes.
62
64 Timestamps refer to specific, unique points in time. On display,
65 systemd will format these in the local timezone as follows:
66 Fri 2012-11-23 23:02:15 CET
68 The weekday is printed in the abbreviated English language form. The
70 formatting is locale-independent.
71 In some cases timestamps are shown in the UTC timezone instead of the
73 local timezone, which is indicated via the "UTC" timezone specifier in
74 the output.
75 In some cases timestamps are shown with microsecond granularity. In
77 this case the sub-second remainder is separated by a full stop from the
78 seconds component.
79
81 When parsing, systemd will accept a similar syntax, but expects no
82 timezone specification, unless it is given as the literal string "UTC"
83 (for the UTC timezone), or is specified to be the locally configured
84 timezone, or the timezone name in the IANA timezone database format.
85 The complete list of timezones supported on your system can be obtained
86 using the "timedatectl list-timezones" (see timedatectl(1)). Using IANA
87 format is recommended over local timezone names, as less prone to
88 errors (eg: with local timezone it's possible to specify daylight
89 saving time in winter, while it's incorrect). The weekday specification
90 is optional, but when the weekday is specified, it must either be in
91 the abbreviated ("Wed") or non-abbreviated ("Wednesday") English
92 language form (case does not matter), and is not subject to the locale
93 choice of the user. Either the date, or the time part may be omitted,
94 in which case the current date or 00:00:00, respectively, is assumed.
95 The seconds component of the time may also be omitted, in which case
96 ":00" is assumed. Year numbers may be specified in full or may be
97 abbreviated (omitting the century).
98 A timestamp is considered invalid if a weekday is specified and the
100 date does not match the specified day of the week.
101 When parsing, systemd will also accept a few special placeholders
103 instead of timestamps: "now" may be used to refer to the current time
104 (or of the invocation of the command that is currently executed).
105 "today", "yesterday", and "tomorrow" refer to 00:00:00 of the current
106 day, the day before, or the next day, respectively.
107 When parsing, systemd will also accept relative time specifications. A
109 time span (see above) that is prefixed with "+" is evaluated to the
110 current time plus the specified time span. Correspondingly, a time span
111 that is prefixed with "-" is evaluated to the current time minus the
112 specified time span. Instead of prefixing the time span with "+" or
113 "-", it may also be suffixed with a space and the word "left" or "ago".
114 Finally, a timespan prefixed with "@" is evaluated relative to the UNIX
116 time epoch 1st Jan, 1970, 00:00.
117 Examples for valid timestamps and their normalized form (assuming the
119 current time was 2012-11-23 18:15:22 and the timezone was UTC+8, for
120 example TZ=Asia/Shanghai):
121 Fri 2012-11-23 11:12:13 → Fri 2012-11-23 11:12:13
123 2012-11-23 11:12:13 → Fri 2012-11-23 11:12:13
124 2012-11-23 11:12:13 UTC → Fri 2012-11-23 19:12:13
125 2012-11-23 → Fri 2012-11-23 00:00:00
126 12-11-23 → Fri 2012-11-23 00:00:00
127 11:12:13 → Fri 2012-11-23 11:12:13
128 11:12 → Fri 2012-11-23 11:12:00
129 now → Fri 2012-11-23 18:15:22
130 today → Fri 2012-11-23 00:00:00
131 today UTC → Fri 2012-11-23 16:00:00
132 yesterday → Fri 2012-11-22 00:00:00
133 tomorrow → Fri 2012-11-24 00:00:00
134 tomorrow Pacific/Auckland → Thu 2012-11-23 19:00:00
135 +3h30min → Fri 2012-11-23 21:45:22
136 -5s → Fri 2012-11-23 18:15:17
137 11min ago → Fri 2012-11-23 18:04:22
138 @1395716396 → Tue 2014-03-25 03:59:56
139 Note that timestamps displayed by remote systems with a non-matching
141 timezone are usually not parsable locally, as the timezone component is
142 not understood (unless it happens to be "UTC").
143 Timestamps may also be specified with microsecond granularity. The
145 sub-second remainder is expected separated by a full stop from the
146 seconds component. Example:
147 2014-03-25 03:59:56.654563
149 In some cases, systemd will display a relative timestamp (relative to
151 the current time, or the time of invocation of the command) instead of
152 or in addition to an absolute timestamp as described above. A relative
153 timestamp is formatted as follows:
154 2 months 5 days ago
156 Note that a relative timestamp is also accepted where a timestamp is
158 expected (see above).
159 Use the timestamp command of systemd-analyze(1) to validate and
161 normalize timestamps for testing purposes.
162
164 Calendar events may be used to refer to one or more points in time in a
165 single expression. They form a superset of the absolute timestamps
166 explained above:
167 Thu,Fri 2012-*-1,5 11:12:13
169 The above refers to 11:12:13 of the first or fifth day of any month of
171 the year 2012, but only if that day is a Thursday or Friday.
172 The weekday specification is optional. If specified, it should consist
174 of one or more English language weekday names, either in the
175 abbreviated (Wed) or non-abbreviated (Wednesday) form (case does not
176 matter), separated by commas. Specifying two weekdays separated by ".."
177 refers to a range of continuous weekdays. "," and ".." may be
178 combined freely.
179 In the date and time specifications, any component may be specified as
181 "*" in which case any value will match. Alternatively, each component
182 can be specified as a list of values separated by commas. Values may be
183 suffixed with "/" and a repetition value, which indicates that the
184 value itself and the value plus all multiples of the repetition value
185 are matched. Two values separated by ".." may be used to indicate a
186 range of values; ranges may also be followed with "/" and a repetition
187 value.
188 A date specification may use "~" to indicate the last day(s) in a
190 month. For example, "*-02~03" means "the third last day in February,"
191 and "Mon *-05~07/1" means "the last Monday in May."
192 The seconds component may contain decimal fractions both in the value
194 and the repetition. All fractions are rounded to 6 decimal places.
195 Either time or date specification may be omitted, in which case the
197 current day and 00:00:00 is implied, respectively. If the second
198 component is not specified, ":00" is assumed.
199 Timezone can be specified as the literal string "UTC", or the local
201 timezone, similar to the supported syntax of timestamps (see above), or
202 the timezone in the IANA timezone database format (also see above).
203 The following special expressions may be used as shorthands for longer
205 normalized forms:
206 minutely → *-*-* *:*:00
208 hourly → *-*-* *:00:00
209 daily → *-*-* 00:00:00
210 monthly → *-*-01 00:00:00
211 weekly → Mon *-*-* 00:00:00
212 yearly → *-01-01 00:00:00
213 quarterly → *-01,04,07,10-01 00:00:00
214 semiannually → *-01,07-01 00:00:00
215 Examples for valid timestamps and their normalized form:
218 Sat,Thu,Mon..Wed,Sat..Sun → Mon..Thu,Sat,Sun *-*-* 00:00:00
220 Mon,Sun 12-*-* 2,1:23 → Mon,Sun 2012-*-* 01,02:23:00
221 Wed *-1 → Wed *-*-01 00:00:00
222 Wed..Wed,Wed *-1 → Wed *-*-01 00:00:00
223 Wed, 17:48 → Wed *-*-* 17:48:00
224 Wed..Sat,Tue 12-10-15 1:2:3 → Tue..Sat 2012-10-15 01:02:03
225 *-*-7 0:0:0 → *-*-07 00:00:00
226 10-15 → *-10-15 00:00:00
227 monday *-12-* 17:00 → Mon *-12-* 17:00:00
228 Mon,Fri *-*-3,1,2 *:30:45 → Mon,Fri *-*-01,02,03 *:30:45
229 12,14,13,12:20,10,30 → *-*-* 12,13,14:10,20,30:00
230 12..14:10,20,30 → *-*-* 12..14:10,20,30:00
231 mon,fri *-1/2-1,3 *:30:45 → Mon,Fri *-01/2-01,03 *:30:45
232 03-05 08:05:40 → *-03-05 08:05:40
233 08:05:40 → *-*-* 08:05:40
234 05:40 → *-*-* 05:40:00
235 Sat,Sun 12-05 08:05:40 → Sat,Sun *-12-05 08:05:40
236 Sat,Sun 08:05:40 → Sat,Sun *-*-* 08:05:40
237 2003-03-05 05:40 → 2003-03-05 05:40:00
238 05:40:23.4200004/3.1700005 → *-*-* 05:40:23.420000/3.170001
239 2003-02..04-05 → 2003-02..04-05 00:00:00
240 2003-03-05 05:40 UTC → 2003-03-05 05:40:00 UTC
241 2003-03-05 → 2003-03-05 00:00:00
242 03-05 → *-03-05 00:00:00
243 hourly → *-*-* *:00:00
244 daily → *-*-* 00:00:00
245 daily UTC → *-*-* 00:00:00 UTC
246 monthly → *-*-01 00:00:00
247 weekly → Mon *-*-* 00:00:00
248 weekly Pacific/Auckland → Mon *-*-* 00:00:00 Pacific/Auckland
249 yearly → *-01-01 00:00:00
250 annually → *-01-01 00:00:00
251 *:2/3 → *-*-* *:02/3:00
252 Calendar events are used by timer units, see systemd.timer(5) for
254 details.
255 Use the calendar command of systemd-analyze(1) to validate and
257 normalize calendar time specifications for testing purposes. The tool
258 also calculates when a specified calendar event would elapse next.
259
261 systemd(1), journalctl(1), systemd.timer(5), systemd.unit(5),
262 systemd.directives(7), systemd-analyze(1)
263systemd 243 SYSTEMD.TIME(7)