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 Internally, systemd generally operates with microsecond time
64 granularity, while the default time unit in user-configurable time
65 spans is usually seconds (see above). This disparity becomes visible
66 when comparing the same settings in the (high-level) unit file syntax
67 with the matching (more low-level) D-Bus properties (which are what
68 systemctl(1)'s show command displays). The former typically are
69 suffixed with "...Sec" to indicate the default unit of seconds, the
70 latter are typically suffixed with "...USec" to indicate the underlying
71 low-level time unit, even if they both encapsulate the very same
72 settings.
73
75 Timestamps refer to specific, unique points in time. On display,
76 systemd will format these in the local timezone as follows:
77 Fri 2012-11-23 23:02:15 CET
79 The weekday is printed in the abbreviated English language form. The
81 formatting is locale-independent.
82 In some cases timestamps are shown in the UTC timezone instead of the
84 local timezone, which is indicated via the "UTC" timezone specifier in
85 the output.
86 In some cases timestamps are shown with microsecond granularity. In
88 this case the sub-second remainder is separated by a full stop from the
89 seconds component.
90
92 When parsing, systemd will accept a similar syntax, but expects no
93 timezone specification, unless it is given as the literal string "UTC"
94 (for the UTC timezone), or is specified to be the locally configured
95 timezone, or the timezone name in the IANA timezone database format.
96 The complete list of timezones supported on your system can be obtained
97 using the "timedatectl list-timezones" (see timedatectl(1)). Using IANA
98 format is recommended over local timezone names, as less prone to
99 errors (e.g. with local timezone it's possible to specify daylight
100 saving time in winter, even though that is not correct). The weekday
101 specification is optional, but when the weekday is specified, it must
102 either be in the abbreviated ("Wed") or non-abbreviated ("Wednesday")
103 English language form (case does not matter), and is not subject to the
104 locale choice of the user. Either the date, or the time part may be
105 omitted, in which case the current date or 00:00:00, respectively, is
106 assumed. The seconds component of the time may also be omitted, in
107 which case ":00" is assumed. Year numbers may be specified in full or
108 may be abbreviated (omitting the century).
109 A timestamp is considered invalid if a weekday is specified and the
111 date does not match the specified day of the week.
112 When parsing, systemd will also accept a few special placeholders
114 instead of timestamps: "now" may be used to refer to the current time
115 (or of the invocation of the command that is currently executed).
116 "today", "yesterday", and "tomorrow" refer to 00:00:00 of the current
117 day, the day before, or the next day, respectively.
118 When parsing, systemd will also accept relative time specifications. A
120 time span (see above) that is prefixed with "+" is evaluated to the
121 current time plus the specified time span. Correspondingly, a time span
122 that is prefixed with "-" is evaluated to the current time minus the
123 specified time span. Instead of prefixing the time span with "+" or
124 "-", it may also be suffixed with a space and the word "left" or "ago".
125 Finally, a timespan prefixed with "@" is evaluated relative to the UNIX
127 time epoch 1st Jan, 1970, 00:00.
128 Examples for valid timestamps and their normalized form (assuming the
130 current time was 2012-11-23 18:15:22 and the timezone was UTC+8, for
131 example "TZ=:Asia/Shanghai"):
132 Fri 2012-11-23 11:12:13 → Fri 2012-11-23 11:12:13
134 2012-11-23 11:12:13 → Fri 2012-11-23 11:12:13
135 2012-11-23 11:12:13 UTC → Fri 2012-11-23 19:12:13
136 2012-11-23 → Fri 2012-11-23 00:00:00
137 12-11-23 → Fri 2012-11-23 00:00:00
138 11:12:13 → Fri 2012-11-23 11:12:13
139 11:12 → Fri 2012-11-23 11:12:00
140 now → Fri 2012-11-23 18:15:22
141 today → Fri 2012-11-23 00:00:00
142 today UTC → Fri 2012-11-23 16:00:00
143 yesterday → Fri 2012-11-22 00:00:00
144 tomorrow → Fri 2012-11-24 00:00:00
145 tomorrow Pacific/Auckland → Thu 2012-11-23 19:00:00
146 +3h30min → Fri 2012-11-23 21:45:22
147 -5s → Fri 2012-11-23 18:15:17
148 11min ago → Fri 2012-11-23 18:04:22
149 @1395716396 → Tue 2014-03-25 03:59:56
150 Note that timestamps displayed by remote systems with a non-matching
152 timezone are usually not parsable locally, as the timezone component is
153 not understood (unless it happens to be "UTC").
154 Timestamps may also be specified with microsecond granularity. The
156 sub-second remainder is expected separated by a full stop from the
157 seconds component. Example:
158 2014-03-25 03:59:56.654563
160 In some cases, systemd will display a relative timestamp (relative to
162 the current time, or the time of invocation of the command) instead of
163 or in addition to an absolute timestamp as described above. A relative
164 timestamp is formatted as follows:
165 2 months 5 days ago
167 Note that a relative timestamp is also accepted where a timestamp is
169 expected (see above).
170 Use the timestamp command of systemd-analyze(1) to validate and
172 normalize timestamps for testing purposes.
173
175 Calendar events may be used to refer to one or more points in time in a
176 single expression. They form a superset of the absolute timestamps
177 explained above:
178 Thu,Fri 2012-*-1,5 11:12:13
180 The above refers to 11:12:13 of the first or fifth day of any month of
182 the year 2012, but only if that day is a Thursday or Friday.
183 The weekday specification is optional. If specified, it should consist
185 of one or more English language weekday names, either in the
186 abbreviated (Wed) or non-abbreviated (Wednesday) form (case does not
187 matter), separated by commas. Specifying two weekdays separated by ".."
188 refers to a range of continuous weekdays. "," and ".." may be
189 combined freely.
190 In the date and time specifications, any component may be specified as
192 "*" in which case any value will match. Alternatively, each component
193 can be specified as a list of values separated by commas. Values may be
194 suffixed with "/" and a repetition value, which indicates that the
195 value itself and the value plus all multiples of the repetition value
196 are matched. Two values separated by ".." may be used to indicate a
197 range of values; ranges may also be followed with "/" and a repetition
198 value, in which case the expression matches all times starting with the
199 start value, and continuing with all multiples of the repetition value
200 relative to the start value, ending at the end value the latest.
201 A date specification may use "~" to indicate the last day(s) in a
203 month. For example, "*-02~03" means "the third last day in February,"
204 and "Mon *-05~07/1" means "the last Monday in May."
205 The seconds component may contain decimal fractions both in the value
207 and the repetition. All fractions are rounded to 6 decimal places.
208 Either time or date specification may be omitted, in which case the
210 current day and 00:00:00 is implied, respectively. If the second
211 component is not specified, ":00" is assumed.
212 Timezone can be specified as the literal string "UTC", or the local
214 timezone, similar to the supported syntax of timestamps (see above), or
215 the timezone in the IANA timezone database format (also see above).
216 The following special expressions may be used as shorthands for longer
218 normalized forms:
219 minutely → *-*-* *:*:00
221 hourly → *-*-* *:00:00
222 daily → *-*-* 00:00:00
223 monthly → *-*-01 00:00:00
224 weekly → Mon *-*-* 00:00:00
225 yearly → *-01-01 00:00:00
226 quarterly → *-01,04,07,10-01 00:00:00
227 semiannually → *-01,07-01 00:00:00
228 Examples for valid timestamps and their normalized form:
231 Sat,Thu,Mon..Wed,Sat..Sun → Mon..Thu,Sat,Sun *-*-* 00:00:00
233 Mon,Sun 12-*-* 2,1:23 → Mon,Sun 2012-*-* 01,02:23:00
234 Wed *-1 → Wed *-*-01 00:00:00
235 Wed..Wed,Wed *-1 → Wed *-*-01 00:00:00
236 Wed, 17:48 → Wed *-*-* 17:48:00
237 Wed..Sat,Tue 12-10-15 1:2:3 → Tue..Sat 2012-10-15 01:02:03
238 *-*-7 0:0:0 → *-*-07 00:00:00
239 10-15 → *-10-15 00:00:00
240 monday *-12-* 17:00 → Mon *-12-* 17:00:00
241 Mon,Fri *-*-3,1,2 *:30:45 → Mon,Fri *-*-01,02,03 *:30:45
242 12,14,13,12:20,10,30 → *-*-* 12,13,14:10,20,30:00
243 12..14:10,20,30 → *-*-* 12..14:10,20,30:00
244 mon,fri *-1/2-1,3 *:30:45 → Mon,Fri *-01/2-01,03 *:30:45
245 03-05 08:05:40 → *-03-05 08:05:40
246 08:05:40 → *-*-* 08:05:40
247 05:40 → *-*-* 05:40:00
248 Sat,Sun 12-05 08:05:40 → Sat,Sun *-12-05 08:05:40
249 Sat,Sun 08:05:40 → Sat,Sun *-*-* 08:05:40
250 2003-03-05 05:40 → 2003-03-05 05:40:00
251 05:40:23.4200004/3.1700005 → *-*-* 05:40:23.420000/3.170001
252 2003-02..04-05 → 2003-02..04-05 00:00:00
253 2003-03-05 05:40 UTC → 2003-03-05 05:40:00 UTC
254 2003-03-05 → 2003-03-05 00:00:00
255 03-05 → *-03-05 00:00:00
256 hourly → *-*-* *:00:00
257 daily → *-*-* 00:00:00
258 daily UTC → *-*-* 00:00:00 UTC
259 monthly → *-*-01 00:00:00
260 weekly → Mon *-*-* 00:00:00
261 weekly Pacific/Auckland → Mon *-*-* 00:00:00 Pacific/Auckland
262 yearly → *-01-01 00:00:00
263 annually → *-01-01 00:00:00
264 *:2/3 → *-*-* *:02/3:00
265 Calendar events are used by timer units, see systemd.timer(5) for
267 details.
268 Use the calendar command of systemd-analyze(1) to validate and
270 normalize calendar time specifications for testing purposes. The tool
271 also calculates when a specified calendar event would occur next.
272
274 systemd(1), journalctl(1), systemd.timer(5), systemd.unit(5),
275 systemd.directives(7), systemd-analyze(1)
276systemd 250 SYSTEMD.TIME(7)