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
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
61 Timestamps refer to specific, unique points in time. On display,
62 systemd will format these in the local timezone as follows:
63 Fri 2012-11-23 23:02:15 CET
65 The weekday is printed in the abbreviated English language form. The
67 formatting is locale-independent.
68 In some cases timestamps are shown in the UTC timezone instead of the
70 local timezone, which is indicated via the "UTC" timezone specifier in
71 the output.
72 In some cases timestamps are shown with microsecond granularity. In
74 this case the sub-second remainder is separated by a full stop from the
75 seconds component.
76
78 When parsing, systemd will accept a similar syntax, but expects no
79 timezone specification, unless it is given as the literal string "UTC"
80 (for the UTC timezone), or is specified to be the locally configured
81 timezone, or the timezone name in the IANA timezone database format.
82 The complete list of timezones supported on your system can be obtained
83 using the "timedatectl list-timezones" (see timedatectl(1)). Using IANA
84 format is recommended over local timezone names, as less prone to
85 errors (eg: with local timezone it's possible to specify daylight
86 saving time in winter, while it's incorrect). The weekday specification
87 is optional, but when the weekday is specified, it must either be in
88 the abbreviated ("Wed") or non-abbreviated ("Wednesday") English
89 language form (case does not matter), and is not subject to the locale
90 choice of the user. Either the date, or the time part may be omitted,
91 in which case the current date or 00:00:00, respectively, is assumed.
92 The seconds component of the time may also be omitted, in which case
93 ":00" is assumed. Year numbers may be specified in full or may be
94 abbreviated (omitting the century).
95 A timestamp is considered invalid if a weekday is specified and the
97 date does not match the specified day of the week.
98 When parsing, systemd will also accept a few special placeholders
100 instead of timestamps: "now" may be used to refer to the current time
101 (or of the invocation of the command that is currently executed).
102 "today", "yesterday", and "tomorrow" refer to 00:00:00 of the current
103 day, the day before, or the next day, respectively.
104 When parsing, systemd will also accept relative time specifications. A
106 time span (see above) that is prefixed with "+" is evaluated to the
107 current time plus the specified time span. Correspondingly, a time span
108 that is prefixed with "-" is evaluated to the current time minus the
109 specified time span. Instead of prefixing the time span with "+" or
110 "-", it may also be suffixed with a space and the word "left" or "ago".
111 Finally, a timespan prefixed with "@" is evaluated relative to the UNIX
113 time epoch 1st Jan, 1970, 00:00.
114 Examples for valid timestamps and their normalized form (assuming the
116 current time was 2012-11-23 18:15:22 and the timezone was UTC+8, for
117 example TZ=Asia/Shanghai):
118 Fri 2012-11-23 11:12:13 → Fri 2012-11-23 11:12:13
120 2012-11-23 11:12:13 → Fri 2012-11-23 11:12:13
121 2012-11-23 11:12:13 UTC → Fri 2012-11-23 19:12:13
122 2012-11-23 → Fri 2012-11-23 00:00:00
123 12-11-23 → Fri 2012-11-23 00:00:00
124 11:12:13 → Fri 2012-11-23 11:12:13
125 11:12 → Fri 2012-11-23 11:12:00
126 now → Fri 2012-11-23 18:15:22
127 today → Fri 2012-11-23 00:00:00
128 today UTC → Fri 2012-11-23 16:00:00
129 yesterday → Fri 2012-11-22 00:00:00
130 tomorrow → Fri 2012-11-24 00:00:00
131 tomorrow Pacific/Auckland → Thu 2012-11-23 19:00:00
132 +3h30min → Fri 2012-11-23 21:45:22
133 -5s → Fri 2012-11-23 18:15:17
134 11min ago → Fri 2012-11-23 18:04:22
135 @1395716396 → Tue 2014-03-25 03:59:56
136 Note that timestamps displayed by remote systems with a non-matching
138 timezone are usually not parsable locally, as the timezone component is
139 not understood (unless it happens to be "UTC").
140 Timestamps may also be specified with microsecond granularity. The
142 sub-second remainder is expected separated by a full stop from the
143 seconds component. Example:
144 2014-03-25 03:59:56.654563
146 In some cases, systemd will display a relative timestamp (relative to
148 the current time, or the time of invocation of the command) instead of
149 or in addition to an absolute timestamp as described above. A relative
150 timestamp is formatted as follows:
151 2 months 5 days ago
153 Note that a relative timestamp is also accepted where a timestamp is
155 expected (see above).
156
158 Calendar events may be used to refer to one or more points in time in a
159 single expression. They form a superset of the absolute timestamps
160 explained above:
161 Thu,Fri 2012-*-1,5 11:12:13
163 The above refers to 11:12:13 of the first or fifth day of any month of
165 the year 2012, but only if that day is a Thursday or Friday.
166 The weekday specification is optional. If specified, it should consist
168 of one or more English language weekday names, either in the
169 abbreviated (Wed) or non-abbreviated (Wednesday) form (case does not
170 matter), separated by commas. Specifying two weekdays separated by ".."
171 refers to a range of continuous weekdays. "," and ".." may be
172 combined freely.
173 In the date and time specifications, any component may be specified as
175 "*" in which case any value will match. Alternatively, each component
176 can be specified as a list of values separated by commas. Values may be
177 suffixed with "/" and a repetition value, which indicates that the
178 value itself and the value plus all multiples of the repetition value
179 are matched. Two values separated by ".." may be used to indicate a
180 range of values; ranges may also be followed with "/" and a repetition
181 value.
182 A date specification may use "~" to indicate the last day(s) in a
184 month. For example, "*-02~03" means "the third last day in February,"
185 and "Mon *-05~07/1" means "the last Monday in May."
186 The seconds component may contain decimal fractions both in the value
188 and the repetition. All fractions are rounded to 6 decimal places.
189 Either time or date specification may be omitted, in which case the
191 current day and 00:00:00 is implied, respectively. If the second
192 component is not specified, ":00" is assumed.
193 Timezone can be specified as the literal string "UTC", or the local
195 timezone, similar to the supported syntax of timestamps (see above), or
196 the timezone in the IANA timezone database format (also see above).
197 The following special expressions may be used as shorthands for longer
199 normalized forms:
200 minutely → *-*-* *:*:00
202 hourly → *-*-* *:00:00
203 daily → *-*-* 00:00:00
204 monthly → *-*-01 00:00:00
205 weekly → Mon *-*-* 00:00:00
206 yearly → *-01-01 00:00:00
207 quarterly → *-01,04,07,10-01 00:00:00
208 semiannually → *-01,07-01 00:00:00
209 Examples for valid timestamps and their normalized form:
212 Sat,Thu,Mon..Wed,Sat..Sun → Mon..Thu,Sat,Sun *-*-* 00:00:00
214 Mon,Sun 12-*-* 2,1:23 → Mon,Sun 2012-*-* 01,02:23:00
215 Wed *-1 → Wed *-*-01 00:00:00
216 Wed..Wed,Wed *-1 → Wed *-*-01 00:00:00
217 Wed, 17:48 → Wed *-*-* 17:48:00
218 Wed..Sat,Tue 12-10-15 1:2:3 → Tue..Sat 2012-10-15 01:02:03
219 *-*-7 0:0:0 → *-*-07 00:00:00
220 10-15 → *-10-15 00:00:00
221 monday *-12-* 17:00 → Mon *-12-* 17:00:00
222 Mon,Fri *-*-3,1,2 *:30:45 → Mon,Fri *-*-01,02,03 *:30:45
223 12,14,13,12:20,10,30 → *-*-* 12,13,14:10,20,30:00
224 12..14:10,20,30 → *-*-* 12..14:10,20,30:00
225 mon,fri *-1/2-1,3 *:30:45 → Mon,Fri *-01/2-01,03 *:30:45
226 03-05 08:05:40 → *-03-05 08:05:40
227 08:05:40 → *-*-* 08:05:40
228 05:40 → *-*-* 05:40:00
229 Sat,Sun 12-05 08:05:40 → Sat,Sun *-12-05 08:05:40
230 Sat,Sun 08:05:40 → Sat,Sun *-*-* 08:05:40
231 2003-03-05 05:40 → 2003-03-05 05:40:00
232 05:40:23.4200004/3.1700005 → *-*-* 05:40:23.420000/3.170001
233 2003-02..04-05 → 2003-02..04-05 00:00:00
234 2003-03-05 05:40 UTC → 2003-03-05 05:40:00 UTC
235 2003-03-05 → 2003-03-05 00:00:00
236 03-05 → *-03-05 00:00:00
237 hourly → *-*-* *:00:00
238 daily → *-*-* 00:00:00
239 daily UTC → *-*-* 00:00:00 UTC
240 monthly → *-*-01 00:00:00
241 weekly → Mon *-*-* 00:00:00
242 weekly Pacific/Auckland → Mon *-*-* 00:00:00 Pacific/Auckland
243 yearly → *-01-01 00:00:00
244 annually → *-01-01 00:00:00
245 *:2/3 → *-*-* *:02/3:00
246 Calendar events are used by timer units, see systemd.timer(5) for
248 details.
249 Use the calendar command of systemd-analyze(1) to validate and
251 normalize calendar time specifications for testing purposes. The tool
252 also calculates when a specified calendar event would elapse next.
253
255 systemd(1), journalctl(1), systemd.timer(5), systemd.unit(5),
256 systemd.directives(7), systemd-analyze(1)
257systemd 239 SYSTEMD.TIME(7)