1SYSTEMD.TIME(7)                  systemd.time                  SYSTEMD.TIME(7)
2
3
4

NAME

6       systemd.time - Time and date specifications
7

DESCRIPTION

9       In systemd, timestamps, time spans, and calendar events are displayed
10       and may be specified in closely related syntaxes.
11

DISPLAYING TIME SPANS

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
17           2h 30min
18
19       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

PARSING TIME SPANS

24       When parsing, systemd will accept the same time span syntax. Separating
25       spaces may be omitted. The following time units are understood:
26
27       •   usec, us, µs
28
29       •   msec, ms
30
31       •   seconds, second, sec, s
32
33       •   minutes, minute, min, m
34
35       •   hours, hour, hr, h
36
37       •   days, day, d
38
39       •   weeks, week, w
40
41       •   months, month, M (defined as 30.44 days)
42
43       •   years, year, y (defined as 365.25 days)
44
45       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
51       Examples for valid time span specifications:
52
53           2 h
54           2hours
55           48hr
56           1y 12month
57           55s500ms
58           300ms20s 5day
59
60       One can use the timespan command of systemd-analyze(1) to normalise a
61       textual time span for testing and validation purposes.
62
63       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

DISPLAYING TIMESTAMPS

75       Timestamps refer to specific, unique points in time. On display,
76       systemd will format these in the local timezone as follows:
77
78           Fri 2012-11-23 23:02:15 CET
79
80       The weekday is printed in the abbreviated English language form. The
81       formatting is locale-independent.
82
83       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
87       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

PARSING TIMESTAMPS

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
110       A timestamp is considered invalid if a weekday is specified and the
111       date does not match the specified day of the week.
112
113       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
119       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
126       Finally, a timespan prefixed with "@" is evaluated relative to the UNIX
127       time epoch 1st Jan, 1970, 00:00.
128
129       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
133             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
151       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
155       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
159           2014-03-25 03:59:56.654563
160
161       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
166           2 months 5 days ago
167
168       Note that a relative timestamp is also accepted where a timestamp is
169       expected (see above).
170
171       Use the timestamp command of systemd-analyze(1) to validate and
172       normalize timestamps for testing purposes.
173

CALENDAR EVENTS

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
179           Thu,Fri 2012-*-1,5 11:12:13
180
181       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
184       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
191       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
202       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
206       The seconds component may contain decimal fractions both in the value
207       and the repetition. All fractions are rounded to 6 decimal places.
208
209       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
213       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
217       The following special expressions may be used as shorthands for longer
218       normalized forms:
219
220               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
229
230       Examples for valid timestamps and their normalized form:
231
232             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
266       Calendar events are used by timer units, see systemd.timer(5) for
267       details.
268
269       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

SEE ALSO

274       systemd(1), journalctl(1), systemd.timer(5), systemd.unit(5),
275       systemd.directives(7), systemd-analyze(1)
276
277
278
279systemd 248                                                    SYSTEMD.TIME(7)
Impressum