X-Git-Url: http://git.ipfire.org/?a=blobdiff_plain;f=man%2Fsystemd.time.xml;h=47229b4a4e87a18072526975ea6141743b6038af;hb=21b3a0fcd1fc4e4c668c4d34115e2e411dc0dceb;hp=aae3accb6c08d156779af4ea18def213e9d64358;hpb=7f5da8bd4fb1ba49ba40195a74ca76bb5d4d1f81;p=thirdparty%2Fsystemd.git
diff --git a/man/systemd.time.xml b/man/systemd.time.xml
index aae3accb6c0..47229b4a4e8 100644
--- a/man/systemd.time.xml
+++ b/man/systemd.time.xml
@@ -57,14 +57,13 @@
Displaying Time Spans
- 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.
+ 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:
2h 30min
- All specified time values are meant to be added up. The
- above hence refers to 150 minutes.
+ 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.
@@ -83,13 +82,13 @@
days, day, d
weeks, week, w
months, month, M (defined as 30.44 days)
- years, year, y (define as 365.25 days)
+ years, year, y (defined as 365.25 days)
- 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 allows for this.
+ 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.
Examples for valid time span specifications:
@@ -110,30 +109,29 @@
Fri 2012-11-23 23:02:15 CET
- The weekday is printed according to the locale choice of the
- user.
+ The weekday is printed in the abbreviated English language form. The formatting is locale-independent.
+
+ 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.
+
+ 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.
Parsing Timestamps
- When parsing, systemd will accept a similar syntax, but
- expects no timezone specification, unless it is given as the
- literal string "UTC". In this case, the time is considered in UTC,
- otherwise in the local timezone. 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).
-
- A timestamp is considered invalid if a weekday is specified
- and the date does not actually match the specified day of the
- week.
+ 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).
+
+ A timestamp is considered invalid if a weekday is specified and the date does not match the specified day of
+ the week.
When parsing, systemd will also accept a few special
placeholders instead of timestamps: now may be
@@ -167,8 +165,6 @@
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:13.9900009 â Fri 2012-11-23 11:12:13
- format_timestamp_us: Fri 2012-11-23 11:12:13.990000
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
@@ -176,28 +172,25 @@
yesterday â Fri 2012-11-22 00:00:00
tomorrow â Fri 2012-11-24 00:00:00
+3h30min â Fri 2012-11-23 21:45:22
- +3h30min UTC â -EINVAL
-5s â Fri 2012-11-23 18:15:17
11min ago â Fri 2012-11-23 18:04:22
- 11min ago UTC â -EINVAL
@1395716396 â Tue 2014-03-25 03:59:56
- Note that timestamps printed by systemd will not be parsed
- correctly by systemd, as the timezone specification is not
- accepted, and printing timestamps is subject to locale settings
- for the weekday, while parsing only accepts English weekday
- names.
+ 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).
- In some cases, systemd will display a relative timestamp
- (relative to the current time, or the time of invocation of the
- command) instead or in addition to an absolute timestamp as
- described above. A relative timestamp is formatted as
- follows:
+ Timestamps may also be specified with microsecond granularity. The sub-second remainder is expected separated
+ by a full stop from the seconds component. Example:
+
+ 2014-03-25 03:59:56.654563
+
+ 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:
- 2 months 5 days ago
+ 2 months 5 days ago
- Note that any relative timestamp will also parse correctly
- where a timestamp is expected. (see above)
+ Note that a relative timestamp is also accepted where a timestamp is expected (see above).
@@ -239,8 +232,9 @@
second component is not specified, :00 is
assumed.
- A timezone specification is not expected, unless it is given
- as the literal string "UTC", similarly to timestamps.
+ 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.
The special expressions
minutely,
@@ -263,38 +257,38 @@
Examples for valid timestamps and their
normalized form:
- 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
+ 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, 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
+ *-*-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
Calendar events are used by timer units, see
systemd.timer5