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

DISPLAYING TIMESTAMPS

61       Timestamps refer to specific, unique points in time. On display,
62       systemd will format these in the local timezone as follows:
63
64           Fri 2012-11-23 23:02:15 CET
65
66       The weekday is printed in the abbreviated English language form. The
67       formatting is locale-independent.
68
69       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
73       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

PARSING TIMESTAMPS

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
96       A timestamp is considered invalid if a weekday is specified and the
97       date does not match the specified day of the week.
98
99       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
105       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
112       Finally, a timespan prefixed with "@" is evaluated relative to the UNIX
113       time epoch 1st Jan, 1970, 00:00.
114
115       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
119             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
137       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
141       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
145           2014-03-25 03:59:56.654563
146
147       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
152           2 months 5 days ago
153
154       Note that a relative timestamp is also accepted where a timestamp is
155       expected (see above).
156

CALENDAR EVENTS

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
162           Thu,Fri 2012-*-1,5 11:12:13
163
164       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
167       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
174       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
183       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
187       The seconds component may contain decimal fractions both in the value
188       and the repetition. All fractions are rounded to 6 decimal places.
189
190       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
194       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
198       The following special expressions may be used as shorthands for longer
199       normalized forms:
200
201               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
210
211       Examples for valid timestamps and their normalized form:
212
213             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
247       Calendar events are used by timer units, see systemd.timer(5) for
248       details.
249
250       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

SEE ALSO

255       systemd(1), journalctl(1), systemd.timer(5), systemd.unit(5),
256       systemd.directives(7), systemd-analyze(1)
257
258
259
260systemd 239                                                    SYSTEMD.TIME(7)
Impressum