Merge pull request #1569 from mustrumr/date-parse-additions

Date parse additions

1 files changed, 49 insertions, 38 deletions

diff --git a/man/systemd.time.xml b/man/systemd.time.xml
index 64358351d5..826e9fc5a5 100644
--- a/man/systemd.time.xml
+++ b/man/systemd.time.xml
@@ -117,10 +117,11 @@
   <refsect1>
     <title>Parsing Timestamps</title>
 
-    <para>When parsing systemd will accept a similar timestamp syntax,
-    but excluding any timezone specification (this limitation might be
-    removed eventually). The weekday specification is optional, but
-    when the weekday is specified it must either be in the abbreviated
+    <para>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 time, otherwise in
+    the local timezone. The weekday specification is optional, but when
+    the weekday is specified it must either be in the abbreviated
     (<literal>Wed</literal>) or non-abbreviated
     (<literal>Wednesday</literal>) English language form (case does
     not matter), and is not subject to the locale choice of the user.
@@ -157,22 +158,29 @@
     00:00.</para>
 
     <para>Examples for valid timestamps and their normalized form
-    (assuming the current time was 2012-11-23 18:15:22):</para>
+    (assuming the current time was 2012-11-23 18:15:22 and the timezone
+    was UTC+8, for example TZ=Asia/Shanghai):</para>
 
     <programlisting>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 → 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
-        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</programlisting>
+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: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
+              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
+           +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</programlisting>
 
     <para>Note that timestamps printed by systemd will not be parsed
     correctly by systemd, as the timezone specification is not
@@ -226,7 +234,8 @@
     second component is not specified, <literal>:00</literal> is
     assumed.</para>
 
-    <para>Timezone names may not be specified.</para>
+    <para>A timezone specification is not expected, unless it is given
+    as the literal string "UTC", similarly to timestamps.</para>
 
     <para>The special expressions
     <literal>minutely</literal>,
@@ -242,7 +251,7 @@
     <literal>*-*-01 00:00:00</literal>,
     <literal>Mon *-*-* 00:00:00</literal>,
     <literal>*-01-01 00:00:00</literal>,
-    <literal>*-01,04,07,10-01 00:00:0</literal> and
+    <literal>*-01,04,07,10-01 00:00:00</literal> and
     <literal>*-01,07-01 00:00:00</literal> respectively.
     </para>
 
@@ -251,31 +260,33 @@
 
 <programlisting>   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 *-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
+               *-*-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
  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
+            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
-    2003-03-05 → 2003-03-05 00:00:00
-         03-05 → *-03-05 00:00:00
-        hourly → *-*-* *:00:00
-         daily → *-*-* 00:00:00
-       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</programlisting>
+          Sat,Sun 08:05:40 → Sat,Sun *-*-* 08:05:40
+          2003-03-05 05:40 → 2003-03-05 05:40: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</programlisting>
 
       <para>Calendar events are used by timer units, see
       <citerefentry><refentrytitle>systemd.timer</refentrytitle><manvolnum>5</manvolnum></citerefentry>