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
161 Calendar events may be used to refer to one or more points in time in a
162 single expression. They form a superset of the absolute timestamps
163 explained above:
164 Thu,Fri 2012-*-1,5 11:12:13
166 The above refers to 11:12:13 of the first or fifth day of any month of
168 the year 2012, but only if that day is a Thursday or Friday.
169 The weekday specification is optional. If specified, it should consist
171 of one or more English language weekday names, either in the
172 abbreviated (Wed) or non-abbreviated (Wednesday) form (case does not
173 matter), separated by commas. Specifying two weekdays separated by ".."
174 refers to a range of continuous weekdays. "," and ".." may be
175 combined freely.
176 In the date and time specifications, any component may be specified as
178 "*" in which case any value will match. Alternatively, each component
179 can be specified as a list of values separated by commas. Values may be
180 suffixed with "/" and a repetition value, which indicates that the
181 value itself and the value plus all multiples of the repetition value
182 are matched. Two values separated by ".." may be used to indicate a
183 range of values; ranges may also be followed with "/" and a repetition
184 value.
185 A date specification may use "~" to indicate the last day(s) in a
187 month. For example, "*-02~03" means "the third last day in February,"
188 and "Mon *-05~07/1" means "the last Monday in May."
189 The seconds component may contain decimal fractions both in the value
191 and the repetition. All fractions are rounded to 6 decimal places.
192 Either time or date specification may be omitted, in which case the
194 current day and 00:00:00 is implied, respectively. If the second
195 component is not specified, ":00" is assumed.
196 Timezone can be specified as the literal string "UTC", or the local
198 timezone, similar to the supported syntax of timestamps (see above), or
199 the timezone in the IANA timezone database format (also see above).
200 The following special expressions may be used as shorthands for longer
202 normalized forms:
203 minutely → *-*-* *:*:00
205 hourly → *-*-* *:00:00
206 daily → *-*-* 00:00:00
207 monthly → *-*-01 00:00:00
208 weekly → Mon *-*-* 00:00:00
209 yearly → *-01-01 00:00:00
210 quarterly → *-01,04,07,10-01 00:00:00
211 semiannually → *-01,07-01 00:00:00
212 Examples for valid timestamps and their normalized form:
215 Sat,Thu,Mon..Wed,Sat..Sun → Mon..Thu,Sat,Sun *-*-* 00:00:00
217 Mon,Sun 12-*-* 2,1:23 → Mon,Sun 2012-*-* 01,02:23:00
218 Wed *-1 → Wed *-*-01 00:00:00
219 Wed..Wed,Wed *-1 → Wed *-*-01 00:00:00
220 Wed, 17:48 → Wed *-*-* 17:48:00
221 Wed..Sat,Tue 12-10-15 1:2:3 → Tue..Sat 2012-10-15 01:02:03
222 *-*-7 0:0:0 → *-*-07 00:00:00
223 10-15 → *-10-15 00:00:00
224 monday *-12-* 17:00 → Mon *-12-* 17:00:00
225 Mon,Fri *-*-3,1,2 *:30:45 → Mon,Fri *-*-01,02,03 *:30:45
226 12,14,13,12:20,10,30 → *-*-* 12,13,14:10,20,30:00
227 12..14:10,20,30 → *-*-* 12..14:10,20,30:00
228 mon,fri *-1/2-1,3 *:30:45 → Mon,Fri *-01/2-01,03 *:30:45
229 03-05 08:05:40 → *-03-05 08:05:40
230 08:05:40 → *-*-* 08:05:40
231 05:40 → *-*-* 05:40:00
232 Sat,Sun 12-05 08:05:40 → Sat,Sun *-12-05 08:05:40
233 Sat,Sun 08:05:40 → Sat,Sun *-*-* 08:05:40
234 2003-03-05 05:40 → 2003-03-05 05:40:00
235 05:40:23.4200004/3.1700005 → *-*-* 05:40:23.420000/3.170001
236 2003-02..04-05 → 2003-02..04-05 00:00:00
237 2003-03-05 05:40 UTC → 2003-03-05 05:40:00 UTC
238 2003-03-05 → 2003-03-05 00:00:00
239 03-05 → *-03-05 00:00:00
240 hourly → *-*-* *:00:00
241 daily → *-*-* 00:00:00
242 daily UTC → *-*-* 00:00:00 UTC
243 monthly → *-*-01 00:00:00
244 weekly → Mon *-*-* 00:00:00
245 weekly Pacific/Auckland → Mon *-*-* 00:00:00 Pacific/Auckland
246 yearly → *-01-01 00:00:00
247 annually → *-01-01 00:00:00
248 *:2/3 → *-*-* *:02/3:00
249 Calendar events are used by timer units, see systemd.timer(5) for
251 details.
252 Use the calendar command of systemd-analyze(1) to validate and
254 normalize calendar time specifications for testing purposes. The tool
255 also calculates when a specified calendar event would elapse next.
256
258 systemd(1), journalctl(1), systemd.timer(5), systemd.unit(5),
259 systemd.directives(7), systemd-analyze(1)
260systemd 241 SYSTEMD.TIME(7)