'\" t
.TH "SYSTEMD\&.TIME" "7" "" "systemd 232" "systemd.time"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
systemd.time \- Time and date specifications
.SH "DESCRIPTION"
.PP
In systemd, timestamps, time spans, and calendar events are displayed and may be specified in closely related syntaxes\&.
.SH "DISPLAYING TIME SPANS"
.PP
Time spans refer to time durations\&. On display, systemd will present time spans as a space\-separated series of time values each suffixed by a time unit\&. Example:
.sp
.if n \{\
.RS 4
.\}
.nf
2h 30min
.fi
.if n \{\
.RE
.\}
.PP
All specified time values are meant to be added up\&. The above hence refers to 150 minutes\&. Display is locale\-independent, only English names for the time units are used\&.
.SH "PARSING TIME SPANS"
.PP
When parsing, systemd will accept the same time span syntax\&. Separating spaces may be omitted\&. The following time units are understood:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
usec, us
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
msec, ms
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
seconds, second, sec, s
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
minutes, minute, min, m
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
hours, hour, hr, h
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
days, day, d
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
weeks, week, w
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
months, month, M (defined as 30\&.44 days)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
years, year, y (defined as 365\&.25 days)
.RE
.PP
If no time unit is specified, generally seconds are assumed, but some exceptions exist and are marked as such\&. In a few cases
"ns",
"nsec"
is accepted too, where the granularity of the time span permits this\&. Parsing is generally locale\-independent, non\-English names for the time units are not accepted\&.
.PP
Examples for valid time span specifications:
.sp
.if n \{\
.RS 4
.\}
.nf
2 h
2hours
48hr
1y 12month
55s500ms
300ms20s 5day
.fi
.if n \{\
.RE
.\}
.SH "DISPLAYING TIMESTAMPS"
.PP
Timestamps refer to specific, unique points in time\&. On display, systemd will format these in the local timezone as follows:
.sp
.if n \{\
.RS 4
.\}
.nf
Fri 2012\-11\-23 23:02:15 CET
.fi
.if n \{\
.RE
.\}
.PP
The weekday is printed in the abbreviated English language form\&. The formatting is locale\-independent\&.
.PP
In some cases timestamps are shown in the UTC timezone instead of the local timezone, which is indicated via the
"UTC"
timezone specifier in the output\&.
.PP
In some cases timestamps are shown with microsecond granularity\&. In this case the sub\-second remainder is separated by a full stop from the seconds component\&.
.SH "PARSING TIMESTAMPS"
.PP
When parsing, systemd will accept a similar syntax, but expects no timezone specification, unless it is given as the literal string
"UTC"
(for the UTC timezone) or is specified to be the locally configured timezone\&. Other timezones than the local and UTC are not supported\&. The weekday specification is optional, but when the weekday is specified, it must either be in the abbreviated ("Wed") or non\-abbreviated ("Wednesday") English language form (case does not matter), and is not subject to the locale choice of the user\&. Either the date, or the time part may be omitted, in which case the current date or 00:00:00, respectively, is assumed\&. The seconds component of the time may also be omitted, in which case ":00" is assumed\&. Year numbers may be specified in full or may be abbreviated (omitting the century)\&.
.PP
A timestamp is considered invalid if a weekday is specified and the date does not match the specified day of the week\&.
.PP
When parsing, systemd will also accept a few special placeholders instead of timestamps:
"now"
may be used to refer to the current time (or of the invocation of the command that is currently executed)\&.
"today",
"yesterday", and
"tomorrow"
refer to 00:00:00 of the current day, the day before, or the next day, respectively\&.
.PP
When parsing, systemd will also accept relative time specifications\&. A time span (see above) that is prefixed with
"+"
is evaluated to the current time plus the specified time span\&. Correspondingly, a time span that is prefixed with
"\-"
is evaluated to the current time minus the specified time span\&. Instead of prefixing the time span with
"+"
or
"\-", it may also be suffixed with a space and the word
"left"
or
"ago"\&.
.PP
Finally, a timespan prefixed with
"@"
is evaluated relative to the UNIX time epoch 1st Jan, 1970, 00:00\&.
.PP
Examples for valid timestamps and their normalized form (assuming the current time was 2012\-11\-23 18:15:22 and the timezone was UTC+8, for example TZ=Asia/Shanghai):
.sp
.if n \{\
.RS 4
.\}
.nf
Fri 2012\-11\-23 11:12:13 → Fri 2012\-11\-23 11:12:13
    2012\-11\-23 11:12:13 → Fri 2012\-11\-23 11:12:13
2012\-11\-23 11:12:13 UTC → Fri 2012\-11\-23 19:12:13
             2012\-11\-23 → Fri 2012\-11\-23 00:00:00
               12\-11\-23 → Fri 2012\-11\-23 00:00:00
               11:12:13 → Fri 2012\-11\-23 11:12:13
                  11:12 → Fri 2012\-11\-23 11:12:00
                    now → Fri 2012\-11\-23 18:15:22
                  today → Fri 2012\-11\-23 00:00:00
              today UTC → Fri 2012\-11\-23 16:00:00
              yesterday → Fri 2012\-11\-22 00:00:00
               tomorrow → Fri 2012\-11\-24 00:00:00
               +3h30min → Fri 2012\-11\-23 21:45:22
                    \-5s → Fri 2012\-11\-23 18:15:17
              11min ago → Fri 2012\-11\-23 18:04:22
            @1395716396 → Tue 2014\-03\-25 03:59:56
.fi
.if n \{\
.RE
.\}
.PP
Note that timestamps displayed by remote systems with a non\-matching timezone are usually not parsable locally, as the timezone component is not understood (unless it happens to be
"UTC")\&.
.PP
Timestamps may also be specified with microsecond granularity\&. The sub\-second remainder is expected separated by a full stop from the seconds component\&. Example:
.sp
.if n \{\
.RS 4
.\}
.nf
2014\-03\-25 03:59:56\&.654563
.fi
.if n \{\
.RE
.\}
.PP
In some cases, systemd will display a relative timestamp (relative to the current time, or the time of invocation of the command) instead of or in addition to an absolute timestamp as described above\&. A relative timestamp is formatted as follows:
.sp
.if n \{\
.RS 4
.\}
.nf
2 months 5 days ago
.fi
.if n \{\
.RE
.\}
.PP
Note that a relative timestamp is also accepted where a timestamp is expected (see above)\&.
.SH "CALENDAR EVENTS"
.PP
Calendar events may be used to refer to one or more points in time in a single expression\&. They form a superset of the absolute timestamps explained above:
.sp
.if n \{\
.RS 4
.\}
.nf
Thu,Fri 2012\-*\-1,5 11:12:13
.fi
.if n \{\
.RE
.\}
.PP
The above refers to 11:12:13 of the first or fifth day of any month of the year 2012, but only if that day is a Thursday or Friday\&.
.PP
The weekday specification is optional\&. If specified, it should consist of one or more English language weekday names, either in the abbreviated (Wed) or non\-abbreviated (Wednesday) form (case does not matter), separated by commas\&. Specifying two weekdays separated by
"\&.\&."
refers to a range of continuous weekdays\&.
","
and
"\&.\&."
may be combined freely\&.
.PP
In the date and time specifications, any component may be specified as
"*"
in which case any value will match\&. Alternatively, each component can be specified as a list of values separated by commas\&. Values may also be suffixed with
"/"
and a repetition value, which indicates that the value itself and the value plus all multiples of the repetition value are matched\&. Each component may also contain a range of values separated by
"\&.\&."\&.
.PP
The seconds component may contain decimal fractions both in the value and the repetition\&. All fractions are rounded to 6 decimal places\&.
.PP
Either time or date specification may be omitted, in which case the current day and 00:00:00 is implied, respectively\&. If the second component is not specified,
":00"
is assumed\&.
.PP
A timezone specification is not expected, unless it is given as the literal string
"UTC", or the local timezone, similar to the supported syntax of timestamps (see above)\&. Non\-local timezones except for UTC are not supported\&.
.PP
The special expressions
"minutely",
"hourly",
"daily",
"monthly",
"weekly",
"yearly",
"quarterly",
"semiannually"
may be used as calendar events which refer to
"*\-*\-*\ \&*:*:00",
"*\-*\-*\ \&*:00:00",
"*\-*\-*\ \&00:00:00",
"*\-*\-01\ \&00:00:00",
"Mon\ \&*\-*\-*\ \&00:00:00",
"*\-01\-01\ \&00:00:00",
"*\-01,04,07,10\-01 00:00:00"
and
"*\-01,07\-01 00:00:00", respectively\&.
.PP
Examples for valid timestamps and their normalized form:
.sp
.if n \{\
.RS 4
.\}
.nf
  Sat,Thu,Mon\&.\&.Wed,Sat\&.\&.Sun → Mon\&.\&.Thu,Sat,Sun *\-*\-* 00:00:00
      Mon,Sun 12\-*\-* 2,1:23 → Mon,Sun 2012\-*\-* 01,02:23:00
                    Wed *\-1 → Wed *\-*\-01 00:00:00
           Wed\&.\&.Wed,Wed *\-1 → Wed *\-*\-01 00:00:00
                 Wed, 17:48 → Wed *\-*\-* 17:48:00
Wed\&.\&.Sat,Tue 12\-10\-15 1:2:3 → Tue\&.\&.Sat 2012\-10\-15 01:02:03
                *\-*\-7 0:0:0 → *\-*\-07 00:00:00
                      10\-15 → *\-10\-15 00:00:00
        monday *\-12\-* 17:00 → Mon *\-12\-* 17:00:00
  Mon,Fri *\-*\-3,1,2 *:30:45 → Mon,Fri *\-*\-01,02,03 *:30:45
       12,14,13,12:20,10,30 → *\-*\-* 12,13,14:10,20,30:00
            12\&.\&.14:10,20,30 → *\-*\-* 12,13,14:10,20,30:00
  mon,fri *\-1/2\-1,3 *:30:45 → Mon,Fri *\-01/2\-01,03 *:30:45
             03\-05 08:05:40 → *\-03\-05 08:05:40
                   08:05:40 → *\-*\-* 08:05:40
                      05:40 → *\-*\-* 05:40:00
     Sat,Sun 12\-05 08:05:40 → Sat,Sun *\-12\-05 08:05:40
           Sat,Sun 08:05:40 → Sat,Sun *\-*\-* 08:05:40
           2003\-03\-05 05:40 → 2003\-03\-05 05:40:00
 05:40:23\&.4200004/3\&.1700005 → 05:40:23\&.420000/3\&.170001
             2003\-02\&.\&.04\-05 → 2003\-02,03,04\-05 00:00:00
       2003\-03\-05 05:40 UTC → 2003\-03\-05 05:40:00 UTC
                 2003\-03\-05 → 2003\-03\-05 00:00:00
                      03\-05 → *\-03\-05 00:00:00
                     hourly → *\-*\-* *:00:00
                      daily → *\-*\-* 00:00:00
                  daily UTC → *\-*\-* 00:00:00 UTC
                    monthly → *\-*\-01 00:00:00
                     weekly → Mon *\-*\-* 00:00:00
                     yearly → *\-01\-01 00:00:00
                   annually → *\-01\-01 00:00:00
                      *:2/3 → *\-*\-* *:02/3:00
.fi
.if n \{\
.RE
.\}
.PP
Calendar events are used by timer units, see
\fBsystemd.timer\fR(5)
for details\&.
.SH "SEE ALSO"
.PP
\fBsystemd\fR(1),
\fBjournalctl\fR(1),
\fBsystemd.timer\fR(5),
\fBsystemd.unit\fR(5),
\fBsystemd.directives\fR(7)