X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?p=elogind.git;a=blobdiff_plain;f=man%2Fsystemd.time.xml;h=da0729725d13022a395a4f3a19f3f612eae4dca9;hp=a837f232c37cd6f1e797ce671dd01018754b02b5;hb=88a60da054759f763e2be7bb88c7f88919c6d46f;hpb=3563b896da77bb2e6abc2ca0f03d8e2f570f1cc7

diff --git a/man/systemd.time.xml b/man/systemd.time.xml
index a837f232c..da0729725 100644
--- a/man/systemd.time.xml
+++ b/man/systemd.time.xml
@@ -1,6 +1,6 @@
 <?xml version='1.0'?> <!--*-nxml-*-->
 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
-        "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
+  "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
 
 <!--
   This file is part of systemd.
@@ -23,271 +23,275 @@
 
 <refentry id="systemd.time">
 
-        <refentryinfo>
-                <title>systemd.time</title>
-                <productname>systemd</productname>
-
-                <authorgroup>
-                        <author>
-                                <contrib>Developer</contrib>
-                                <firstname>Lennart</firstname>
-                                <surname>Poettering</surname>
-                                <email>lennart@poettering.net</email>
-                        </author>
-                </authorgroup>
-        </refentryinfo>
-
-        <refmeta>
-                <refentrytitle>systemd.time</refentrytitle>
-                <manvolnum>7</manvolnum>
-        </refmeta>
-
-        <refnamediv>
-                <refname>systemd.time</refname>
-                <refpurpose>Time and date specifications</refpurpose>
-        </refnamediv>
-
-        <refsect1>
-                <title>Description</title>
-
-                <para>In systemd, timestamps, time spans, and calendar
-                events are displayed and may be specified in closely
-                related syntaxes.</para>
-        </refsect1>
-
-        <refsect1>
-                <title>Displaying Time Spans</title>
-
-                <para>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.</para>
-
-                <programlisting>2h 30min</programlisting>
-
-                <para>All specified time values are meant to be added
-                up. The above hence refers to 150 minutes.</para>
-        </refsect1>
-
-        <refsect1>
-                <title>Parsing Time Spans</title>
-
-                <para>When parsing, systemd will accept the same
-                time span syntax. Separating spaces may be omitted. The
-                following time units are understood:</para>
-
-                <itemizedlist>
-                        <listitem><para>usec, us</para></listitem>
-                        <listitem><para>msec, ms</para></listitem>
-                        <listitem><para>seconds, second, sec, s</para></listitem>
-                        <listitem><para>minutes, minute, min, m</para></listitem>
-                        <listitem><para>hours, hour, hr, h</para></listitem>
-                        <listitem><para>days, day, d</para></listitem>
-                        <listitem><para>weeks, week, w</para></listitem>
-                        <listitem><para>months, month</para></listitem>
-                        <listitem><para>years, year, y</para></listitem>
-                </itemizedlist>
-
-                <para>If no time unit is specified, generally seconds
-                are assumed, but some exceptions exist and are marked
-                as such. In a few cases <literal>ns</literal>,
-                <literal>nsec</literal> is accepted too, where the
-                granularity of the time span allows for this.</para>
-
-                <para>Examples for valid time span specifications:</para>
-
-                <programlisting>2 h
+  <refentryinfo>
+    <title>systemd.time</title>
+    <productname>systemd</productname>
+
+    <authorgroup>
+      <author>
+        <contrib>Developer</contrib>
+        <firstname>Lennart</firstname>
+        <surname>Poettering</surname>
+        <email>lennart@poettering.net</email>
+      </author>
+    </authorgroup>
+  </refentryinfo>
+
+  <refmeta>
+    <refentrytitle>systemd.time</refentrytitle>
+    <manvolnum>7</manvolnum>
+  </refmeta>
+
+  <refnamediv>
+    <refname>systemd.time</refname>
+    <refpurpose>Time and date specifications</refpurpose>
+  </refnamediv>
+
+  <refsect1>
+    <title>Description</title>
+
+    <para>In systemd, timestamps, time spans, and calendar events are
+    displayed and may be specified in closely related syntaxes.</para>
+  </refsect1>
+
+  <refsect1>
+    <title>Displaying Time Spans</title>
+
+    <para>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.</para>
+
+    <programlisting>2h 30min</programlisting>
+
+    <para>All specified time values are meant to be added up. The
+    above hence refers to 150 minutes.</para>
+  </refsect1>
+
+  <refsect1>
+    <title>Parsing Time Spans</title>
+
+    <para>When parsing, systemd will accept the same time span syntax.
+    Separating spaces may be omitted. The following time units are
+    understood:</para>
+
+    <itemizedlist>
+      <listitem><para>usec, us</para></listitem>
+      <listitem><para>msec, ms</para></listitem>
+      <listitem><para>seconds, second, sec, s</para></listitem>
+      <listitem><para>minutes, minute, min, m</para></listitem>
+      <listitem><para>hours, hour, hr, h</para></listitem>
+      <listitem><para>days, day, d</para></listitem>
+      <listitem><para>weeks, week, w</para></listitem>
+      <listitem><para>months, month</para></listitem>
+      <listitem><para>years, year, y</para></listitem>
+    </itemizedlist>
+
+    <para>If no time unit is specified, generally seconds are assumed,
+    but some exceptions exist and are marked as such. In a few cases
+    <literal>ns</literal>, <literal>nsec</literal> is accepted too,
+    where the granularity of the time span allows for this.</para>
+
+    <para>Examples for valid time span specifications:</para>
+
+    <programlisting>2 h
 2hours
 48hr
 1y 12month
 55s500ms
 300ms20s 5day</programlisting>
-        </refsect1>
-
-        <refsect1>
-                <title>Displaying Timestamps</title>
-
-                <para>Timestamps refer to specific, unique points in
-                time. On display, systemd will format these in the
-                local timezone as follows:</para>
-
-                <programlisting>Fri 2012-11-23 23:02:15 CET</programlisting>
-
-                <para>The weekday is printed according to the locale
-                choice of the user.</para>
-        </refsect1>
-
-        <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 (<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. Either the
-                date, or the time part may be omitted, in which case
-                the current date or 00:00:00, resp., 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).</para>
-
-                <para>A timestamp is considered invalid if a weekday
-                is specified and the date does not actually match the
-                specified day of the week.</para>
-
-                <para>When parsing, systemd will also accept a few
-                special placeholders instead of timestamps:
-                <literal>now</literal> may be used to refer to the
-                current time (or of the invocation of the command
-                that is currently executed). <literal>today</literal>,
-                <literal>yesterday</literal>,
-                <literal>tomorrow</literal> refer to 00:00:00 of the
-                current day, the day before or the next day,
-                respectively.</para>
-
-                <para>When parsing, systemd will also accept relative
-                time specifications. A time span (see above) that is
-                prefixed with <literal>+</literal> is evaluated to the
-                current time plus the specified
-                time span. Correspondingly, a time span that is prefixed
-                with <literal>-</literal> is evaluated to the current
-                time minus the specified time span. Instead of
-                prefixing the time span with <literal>-</literal>, it
-                may also be suffixed with a space and the word
-                <literal>ago</literal>.</para>
-
-                <para>Examples for valid timestamps and their
-                normalized form (assuming the current time was
-                2012-11-23 18:15:22):</para>
-
-                <programlisting>Fri 2012-11-23 11:12:13 → Fri 2012-11-23 11:12:13
+  </refsect1>
+
+  <refsect1>
+    <title>Displaying Timestamps</title>
+
+    <para>Timestamps refer to specific, unique points in time. On
+    display, systemd will format these in the local timezone as
+    follows:</para>
+
+    <programlisting>Fri 2012-11-23 23:02:15 CET</programlisting>
+
+    <para>The weekday is printed according to the locale choice of the
+    user.</para>
+  </refsect1>
+
+  <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
+    (<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.
+    Either the date, or the time part may be omitted, in which case
+    the current date or 00:00:00, resp., 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).</para>
+
+    <para>A timestamp is considered invalid if a weekday is specified
+    and the date does not actually match the specified day of the
+    week.</para>
+
+    <para>When parsing, systemd will also accept a few special
+    placeholders instead of timestamps: <literal>now</literal> may be
+    used to refer to the current time (or of the invocation of the
+    command that is currently executed). <literal>today</literal>,
+    <literal>yesterday</literal>, <literal>tomorrow</literal> refer to
+    00:00:00 of the current day, the day before or the next day,
+    respectively.</para>
+
+    <para>When parsing, systemd will also accept relative time
+    specifications. A time span (see above) that is prefixed with
+    <literal>+</literal> is evaluated to the current time plus the
+    specified time span. Correspondingly, a time span that is prefixed
+    with <literal>-</literal> is evaluated to the current time minus
+    the specified time span. Instead of prefixing the time span with
+    <literal>+</literal> or <literal>-</literal>, it may also be
+    suffixed with a space and the word <literal>left</literal> or
+    <literal>ago</literal>.</para>
+
+    <para>Finally, a timespan prefixed with <literal>@</literal> is
+    evaluated relative to the UNIX time epoch 1st Jan, 1970,
+    00:00.</para>
+
+    <para>Examples for valid timestamps and their normalized form
+    (assuming the current time was 2012-11-23 18:15:22):</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</programlisting>
-
-                <para>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.</para>
-
-                <para>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:</para>
-
-                <para>2 months 5 days ago</para>
-
-                <para>Note that any relative timestamp will also parse
-                correctly where a timestamp is expected. (see above)</para>
-        </refsect1>
-
-        <refsect1>
-                <title>Calendar Events</title>
-
-                <para>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:</para>
-
-                <programlisting>Thu,Fri 2012-*-1,5 11:12:13</programlisting>
-
-                <para>The above refers to 11:12:13 of the first or
-                fifth day of any month of the year 2012, given that it
-                is a Thursday or Friday.</para>
-
-                <para>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 <literal>-</literal> refers to a
-                range of continuous weekdays. <literal>,</literal> and
-                <literal>-</literal> may be combined freely.</para>
-
-                <para>In the date and time specifications, any
-                component may be specified as <literal>*</literal> 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
-                <literal>/</literal> and a repetition value, which
-                indicates that the value and all values plus multiples
-                of the repetition value are matched.</para>
-
-                <para>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, <literal>:00</literal> is assumed.</para>
-
-                <para>Timezone names may not be specified.</para>
-
-                <para>The special expressions
-                <literal>hourly</literal>, <literal>daily</literal>,
-                <literal>monthly</literal> and <literal>weekly</literal>
-                may be used as calendar events which refer to
-                <literal>*-*-* *:00:00</literal>, <literal>*-*-*
-                00:00:00</literal>, <literal>*-*-01 00:00:00</literal> and
-                <literal>Mon *-*-* 00:00:00</literal>,
-                respectively.</para>
-
-                <para>Examples for valid timestamps and their
-                normalized form:</para>
+       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>
+
+    <para>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.</para>
+
+    <para>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:</para>
+
+    <para>2 months 5 days ago</para>
+
+    <para>Note that any relative timestamp will also parse correctly
+    where a timestamp is expected. (see above)</para>
+  </refsect1>
+
+  <refsect1>
+    <title>Calendar Events</title>
+
+    <para>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:</para>
+
+    <programlisting>Thu,Fri 2012-*-1,5 11:12:13</programlisting>
+
+    <para>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.</para>
+
+    <para>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 <literal>-</literal> refers to a range of
+    continuous weekdays. <literal>,</literal> and <literal>-</literal>
+    may be combined freely.</para>
+
+    <para>In the date and time specifications, any component may be
+    specified as <literal>*</literal> 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
+    <literal>/</literal> and a repetition value, which indicates that
+    the value and all values plus multiples of the repetition value
+    are matched.</para>
+
+    <para>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, <literal>:00</literal> is
+    assumed.</para>
+
+    <para>Timezone names may not be specified.</para>
+
+    <para>The special expressions
+    <literal>minutely</literal>,
+    <literal>hourly</literal>, <literal>daily</literal>,
+    <literal>monthly</literal>, <literal>weekly</literal>,
+    <literal>yearly</literal>,
+    <literal>quarterly</literal>,
+    <literal>semiannually</literal> may be used as
+    calendar events which refer to
+    <literal>*-*-* *:*:00</literal>,
+    <literal>*-*-* *:00:00</literal>,
+    <literal>*-*-* 00:00:00</literal>,
+    <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,07-01 00:00:00</literal> respectively.
+    </para>
+
+    <para>Examples for valid timestamps and their
+    normalized form:</para>
 
 <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
-                     *:2/3 → *-*-* *:02/3:00</programlisting>
-
-                  <para>Calendar events are used by timer units, see
-                  <citerefentry><refentrytitle>systemd.timer</refentrytitle><manvolnum>5</manvolnum></citerefentry>
-                  for details.</para>
-
-        </refsect1>
-
-        <refsect1>
-                  <title>See Also</title>
-                  <para>
-                          <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
-                          <citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
-                          <citerefentry><refentrytitle>systemd.timer</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
-                          <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
-                          <citerefentry><refentrytitle>systemd.directives</refentrytitle><manvolnum>7</manvolnum></citerefentry>
-                  </para>
-        </refsect1>
+    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>
+
+      <para>Calendar events are used by timer units, see
+      <citerefentry><refentrytitle>systemd.timer</refentrytitle><manvolnum>5</manvolnum></citerefentry>
+      for details.</para>
+
+  </refsect1>
+
+  <refsect1>
+      <title>See Also</title>
+      <para>
+        <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
+        <citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
+        <citerefentry><refentrytitle>systemd.timer</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
+        <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
+        <citerefentry><refentrytitle>systemd.directives</refentrytitle><manvolnum>7</manvolnum></citerefentry>
+      </para>
+  </refsect1>
 
 </refentry>