From: наб Date: Fri, 8 Sep 2023 16:00:12 +0000 (+0200) Subject: systemd.time.7: rewrite Parsing Timestamps section X-Git-Tag: v255-rc1~506 X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=eed99fe995c585ea316a942793e9379aafbf19c9;p=thirdparty%2Fsystemd.git systemd.time.7: rewrite Parsing Timestamps section --- diff --git a/man/systemd.time.xml b/man/systemd.time.xml index 9fbb7abf07c..f6a4550ac48 100644 --- a/man/systemd.time.xml +++ b/man/systemd.time.xml @@ -108,37 +108,52 @@ Parsing Timestamps - 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, the timezone name in the IANA timezone database format, - or in the RFC 3339 profile of ISO 8601, as - Z or +05:30 - appended directly after the timestamp. The complete - list of timezones supported on your system can be obtained using the timedatectl + When parsing, systemd will accept a similar syntax, but some fields can be omitted, + and the space between the date and time can be replaced with a T + (à la the RFC 3339 profile of ISO 8601); + thus, in CET, the following are all identical: + Fri 2012-11-23 23:02:15 CET, + Fri 2012-11-23T23:02:15, + 2012-11-23T23:02:15 CET, + 2012-11-23 23:02:15. + + The timezone defaults to the current timezone if not specified explicitly. + It may be given after a space, like above, in which case it can be: + UTC, + an entry in the installed IANA timezone database (CET, Asia/Tokyo, &c.; + complete list obtainable with timedatectl list-timezones (see - timedatectl1). Using - IANA format is recommended over local timezone names, as less prone to errors (e.g. with local timezone - it's possible to specify daylight saving time in winter, even though that is not correct). The weekday - specification is optional, but when the weekday is specified, it must either be in the abbreviated + timedatectl1)), + or ±05, + ±0530, + ±05:30, + Z. + + It may also be affixed directly to the timestamp, in which case it must correspond + to one of the formats defined in the + RFC 3339 profile of ISO 8601: + ±05:30 or Z. + Thus, the following are also identical to the above: + 2012-11-23T23:02:15+01:00, + 2012-11-23 22:02:15Z. + + A timestamp can start with a field containing a weekday, which can be in an 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). + does not matter), regardless of the locale. + However, if a weekday is specified and doesn't match the date, the timestamp is rejected. - A timestamp is considered invalid if a weekday is specified and the date does not match the specified day of - the week. + If the date is omitted, it defaults to today. If the time is omitted, it defaults to 00:00:00. + Fractional seconds can be specified down to 1µs precision. The seconds field can also be omitted, defaulting to 0. - When parsing, systemd will also accept a few special - placeholders instead of timestamps: now may be + There are special tokens that can be used in place 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. - When parsing, systemd will also accept relative time - specifications. A time span (see above) that is prefixed with + Relative times are also accepted: a time span (see above) 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 @@ -147,9 +162,8 @@ suffixed with a space and the word left or ago. - Finally, a timespan prefixed with @ is - evaluated relative to the UNIX time epoch 1st Jan, 1970, - 00:00. + Finally, an integer prefixed with @ is + evaluated relative to the UNIX epoch – 1970-01-01 00:00:00 UTC. 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):