man/systemd.time.xml

   1 <?xml version='1.0'?> <!--*-nxml-*-->
   2 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
   3   "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
   4 <!-- SPDX-License-Identifier: LGPL-2.1-or-later -->
   5
   6 <refentry id="systemd.time">
   7
   8   <refentryinfo>
   9     <title>systemd.time</title>
  10     <productname>systemd</productname>
  11   </refentryinfo>
  12
  13   <refmeta>
  14     <refentrytitle>systemd.time</refentrytitle>
  15     <manvolnum>7</manvolnum>
  16   </refmeta>
  17
  18   <refnamediv>
  19     <refname>systemd.time</refname>
  20     <refpurpose>Time and date specifications</refpurpose>
  21   </refnamediv>
  22
  23   <refsect1>
  24     <title>Description</title>
  25
  26     <para>In systemd, timestamps, time spans, and calendar events are
  27     displayed and may be specified in closely related syntaxes.</para>
  28   </refsect1>
  29
  30   <refsect1>
  31     <title>Displaying Time Spans</title>
  32
  33     <para>Time spans refer to time durations. On display, systemd will present time spans as a space-separated series
  34     of time values each suffixed by a time unit. Example:</para>
  35
  36     <programlisting>2h 30min</programlisting>
  37
  38     <para>All specified time values are meant to be added up. The above hence refers to 150 minutes. Display is
  39     locale-independent, only English names for the time units are used.</para>
  40   </refsect1>
  41
  42   <refsect1>
  43     <title>Parsing Time Spans</title>
  44
  45     <para>When parsing, systemd will accept the same time span syntax.
  46     Separating spaces may be omitted. The following time units are
  47     understood:</para>
  48
  49     <itemizedlist>
  50       <listitem><para>usec, us, μs</para></listitem>
  51       <listitem><para>msec, ms</para></listitem>
  52       <listitem><para>seconds, second, sec, s</para></listitem>
  53       <listitem><para>minutes, minute, min, m</para></listitem>
  54       <listitem><para>hours, hour, hr, h</para></listitem>
  55       <listitem><para>days, day, d</para></listitem>
  56       <listitem><para>weeks, week, w</para></listitem>
  57       <listitem><para>months, month, M (defined as 30.44 days)</para></listitem>
  58       <listitem><para>years, year, y (defined as 365.25 days)</para></listitem>
  59     </itemizedlist>
  60
  61     <para>If no time unit is specified, generally seconds are assumed, but some exceptions exist and are marked as
  62     such. In a few cases <literal>ns</literal>, <literal>nsec</literal> is accepted too, where the granularity of the
  63     time span permits this. Parsing is generally locale-independent, non-English names for the time units are not
  64     accepted.</para>
  65
  66     <para>Examples for valid time span specifications:</para>
  67
  68     <programlisting>2 h
  69 2hours
  70 48hr
  71 1y 12month
  72 55s500ms
  73 300ms20s 5day</programlisting>
  74
  75     <para>One can use the <command>timespan</command> command of
  76     <citerefentry><refentrytitle>systemd-analyze</refentrytitle><manvolnum>1</manvolnum></citerefentry>
  77     to normalise a textual time span for testing and validation purposes.</para>
  78
  79     <para>Internally, systemd generally operates with microsecond time granularity, while the default time
  80     unit in user-configurable time spans is usually seconds (see above). This disparity becomes visible when
  81     comparing the same settings in the (high-level) unit file syntax with the matching (more low-level) D-Bus
  82     properties (which are what
  83     <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>'s
  84     <command>show</command> command displays). The former typically are suffixed with <literal>…Sec</literal>
  85     to indicate the default unit of seconds, the latter are typically suffixed with <literal>…USec</literal>
  86     to indicate the underlying low-level time unit, even if they both encapsulate the very same
  87     settings.</para>
  88   </refsect1>
  89
  90   <refsect1>
  91     <title>Displaying Timestamps</title>
  92
  93     <para>Timestamps refer to specific, unique points in time. On
  94     display, systemd will format these in the local timezone as
  95     follows:</para>
  96
  97     <programlisting>Fri 2012-11-23 23:02:15 CET</programlisting>
  98
  99     <para>The weekday is printed in the abbreviated English language form. The formatting is locale-independent.</para>
 100
 101     <para>In some cases timestamps are shown in the UTC timezone instead of the local timezone, which is indicated via
 102     the <literal>UTC</literal> timezone specifier in the output.</para>
 103
 104     <para>In some cases timestamps are shown with microsecond granularity. In this case the sub-second remainder is
 105     separated by a full stop from the seconds component.</para>
 106   </refsect1>
 107
 108   <refsect1>
 109     <title>Parsing Timestamps</title>
 110
 111     <para>When parsing, systemd will accept a similar syntax, but some fields can be omitted,
 112     and the space between the date and time can be replaced with a <literal>T</literal>
 113     (à la the <ulink url="https://tools.ietf.org/html/rfc3339">RFC 3339</ulink> profile of ISO 8601);
 114     thus, in CET, the following are all identical:
 115     <literal>Fri 2012-11-23 23:02:15 CET</literal>,
 116     <literal>Fri 2012-11-23T23:02:15</literal>,
 117     <literal>2012-11-23T23:02:15 CET</literal>,
 118     <literal>2012-11-23 23:02:15</literal>.</para>
 119
 120     <para>The timezone defaults to the current timezone if not specified explicitly.
 121     It may be given after a space, like above, in which case it can be:
 122     <literal>UTC</literal>,
 123     an entry in the installed IANA timezone database (<literal>CET</literal>, <literal>Asia/Tokyo</literal>, &amp;c.;
 124     complete list obtainable with <literal>timedatectl
 125     list-timezones</literal> (see
 126     <citerefentry><refentrytitle>timedatectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>)),
 127     or <literal>±<replaceable>05</replaceable></literal>,
 128     <literal>±<replaceable>05</replaceable><replaceable>30</replaceable></literal>,
 129     <literal>±<replaceable>05</replaceable>:<replaceable>30</replaceable></literal>,
 130     <literal>Z</literal>.</para>   <!-- glibc %z -->
 131
 132     <para>It may also be affixed directly to the timestamp, in which case it must correspond
 133     to one of the formats defined in the
 134     <ulink url="https://tools.ietf.org/html/rfc3339">RFC 3339</ulink> profile of ISO 8601:
 135     <literal>±<replaceable>05</replaceable>:<replaceable>30</replaceable></literal> or <literal>Z</literal>.
 136     Thus, the following are also identical to the above:
 137     <literal>2012-11-23T23:02:15+01:00</literal>,
 138     <literal>2012-11-23 22:02:15Z</literal>.</para>
 139
 140     <para>A timestamp can start with a field containing a weekday, which can be in an abbreviated
 141     (<literal>Wed</literal>) or non-abbreviated (<literal>Wednesday</literal>) English language form (case
 142     does not matter), regardless of the locale.
 143     However, if a weekday <emphasis>is</emphasis> specified and doesn't match the date, the timestamp is rejected.</para>
 144
 145     <para>If the date is omitted, it defaults to today. If the time is omitted, it defaults to 00:00:00.
 146     Fractional seconds can be specified down to 1µs precision. The seconds field can also be omitted, defaulting to 0.</para>
 147
 148     <para>There are special tokens that can be used in place of timestamps:
 149     <literal>now</literal> may be
 150     used to refer to the current time (or of the invocation of the
 151     command that is currently executed). <literal>today</literal>,
 152     <literal>yesterday</literal>, and <literal>tomorrow</literal> refer to
 153     00:00:00 of the current day, the day before, or the next day,
 154     respectively.</para>
 155
 156     <para>Relative times are also accepted: a time span (see above) prefixed with
 157     <literal>+</literal> is evaluated to the current time plus the
 158     specified time span. Correspondingly, a time span that is prefixed
 159     with <literal>-</literal> is evaluated to the current time minus
 160     the specified time span. Instead of prefixing the time span with
 161     <literal>+</literal> or <literal>-</literal>, it may also be
 162     suffixed with a space and the word <literal>left</literal> or
 163     <literal>ago</literal>.</para>
 164
 165     <para>Finally, an integer prefixed with <literal>@</literal> is
 166     evaluated relative to the UNIX epoch – 1970-01-01 00:00:00 UTC.</para>
 167
 168     <para>Examples for valid timestamps and their normalized form (assuming the current time was 2012-11-23
 169     18:15:22 and the timezone was UTC+8, for example <literal>TZ=:Asia/Shanghai</literal>):</para>
 170
 171     <programlisting>  Fri 2012-11-23 11:12:13 → Fri 2012-11-23 11:12:13
 172       2012-11-23 11:12:13 → Fri 2012-11-23 11:12:13
 173   2012-11-23 11:12:13 UTC → Fri 2012-11-23 19:12:13
 174      2012-11-23T11:12:13Z → Fri 2012-11-23 19:12:13
 175    2012-11-23T11:12+02:00 → Fri 2012-11-23 17:12:00
 176                2012-11-23 → Fri 2012-11-23 00:00:00
 177                  12-11-23 → Fri 2012-11-23 00:00:00
 178                  11:12:13 → Fri 2012-11-23 11:12:13
 179                     11:12 → Fri 2012-11-23 11:12:00
 180                       now → Fri 2012-11-23 18:15:22
 181                     today → Fri 2012-11-23 00:00:00
 182                 today UTC → Fri 2012-11-23 16:00:00
 183                 yesterday → Fri 2012-11-22 00:00:00
 184                  tomorrow → Fri 2012-11-24 00:00:00
 185 tomorrow Pacific/Auckland → Thu 2012-11-23 19:00:00
 186                  +3h30min → Fri 2012-11-23 21:45:22
 187                       -5s → Fri 2012-11-23 18:15:17
 188                 11min ago → Fri 2012-11-23 18:04:22
 189               @1395716396 → Tue 2014-03-25 03:59:56</programlisting>
 190
 191     <para>Note that timestamps displayed by remote systems with a non-matching timezone are usually not parsable
 192     locally, as the timezone component is not understood (unless it happens to be <literal>UTC</literal>).</para>
 193
 194     <para>Timestamps may also be specified with microsecond granularity. The sub-second remainder is expected separated
 195     by a full stop from the seconds component. Example:</para>
 196
 197     <programlisting>2014-03-25 03:59:56.654563</programlisting>
 198
 199     <para>In some cases, systemd will display a relative timestamp (relative to the current time, or the time of
 200     invocation of the command) instead of or in addition to an absolute timestamp as described above. A relative
 201     timestamp is formatted as follows:</para>
 202
 203     <programlisting>2 months 5 days ago</programlisting>
 204
 205     <para>Note that a relative timestamp is also accepted where a timestamp is expected (see above).</para>
 206
 207     <para>Use the <command>timestamp</command> command of
 208     <citerefentry><refentrytitle>systemd-analyze</refentrytitle><manvolnum>1</manvolnum></citerefentry> to
 209     validate and normalize timestamps for testing purposes.</para>
 210   </refsect1>
 211
 212   <refsect1>
 213     <title>Calendar Events</title>
 214
 215     <para>Calendar events may be used to refer to one or more points
 216     in time in a single expression. They form a superset of the
 217     absolute timestamps explained above:</para>
 218
 219     <programlisting>Thu,Fri 2012-*-1,5 11:12:13</programlisting>
 220
 221     <para>The above refers to 11:12:13 of the first or fifth day of
 222     any month of the year 2012, but only if that day is a Thursday or
 223     Friday.</para>
 224
 225     <para>The weekday specification is optional. If specified, it
 226     should consist of one or more English language weekday names,
 227     either in the abbreviated (Wed) or non-abbreviated (Wednesday)
 228     form (case does not matter), separated by commas. Specifying two
 229     weekdays separated by <literal>..</literal> refers to a range of
 230     continuous weekdays. <literal>,</literal> and <literal>..</literal>
 231     may be combined freely.</para>
 232
 233     <para>In the date and time specifications, any component may be specified as <literal>*</literal> in
 234     which case any value will match. Alternatively, each component can be specified as a list of values
 235     separated by commas. Values may be suffixed with <literal>/</literal> and a repetition value, which
 236     indicates that the value itself and the value plus all multiples of the repetition value are matched.
 237     Two values separated by <literal>..</literal> may be used to indicate a range of values; ranges may also
 238     be followed with <literal>/</literal> and a repetition value, in which case the expression matches all
 239     times starting with the start value, and continuing with all multiples of the repetition value relative
 240     to the start value, ending at the end value the latest.</para>
 241
 242     <para>A date specification may use <literal>~</literal> to indicate the last day in a month. For example,
 243     <literal>*-02~03</literal> means "the third last day in February," and <literal>Mon *-05~07/1</literal>
 244     means "the last Monday in May."</para>
 245
 246     <para>The seconds component may contain decimal fractions both in
 247     the value and the repetition. All fractions are rounded to 6
 248     decimal places.</para>
 249
 250     <para>Either time or date specification may be omitted, in which
 251     case *-*-* and 00:00:00 is implied, respectively. If the
 252     seconds component is not specified, <literal>:00</literal> is
 253     assumed.</para>
 254
 255     <para>Timezone can be specified as the literal string <literal>UTC</literal>, or
 256     the local timezone, similar to the supported syntax of timestamps (see above), or the timezone
 257     in the IANA timezone database format (also see above).</para>
 258
 259   <para>The following special expressions may be used as shorthands for longer normalized forms:</para>
 260
 261     <programlisting>    minutely → *-*-* *:*:00
 262       hourly → *-*-* *:00:00
 263        daily → *-*-* 00:00:00
 264      monthly → *-*-01 00:00:00
 265       weekly → Mon *-*-* 00:00:00
 266       yearly → *-01-01 00:00:00
 267    quarterly → *-01,04,07,10-01 00:00:00
 268 semiannually → *-01,07-01 00:00:00
 269    </programlisting>
 270
 271     <para>Examples for valid timestamps and their
 272     normalized form:</para>
 273
 274 <programlisting>  Sat,Thu,Mon..Wed,Sat..Sun → Mon..Thu,Sat,Sun *-*-* 00:00:00
 275       Mon,Sun 12-*-* 2,1:23 → Mon,Sun 2012-*-* 01,02:23:00
 276                     Wed *-1 → Wed *-*-01 00:00:00
 277            Wed..Wed,Wed *-1 → Wed *-*-01 00:00:00
 278                  Wed, 17:48 → Wed *-*-* 17:48:00
 279 Wed..Sat,Tue 12-10-15 1:2:3 → Tue..Sat 2012-10-15 01:02:03
 280                 *-*-7 0:0:0 → *-*-07 00:00:00
 281                       10-15 → *-10-15 00:00:00
 282         monday *-12-* 17:00 → Mon *-12-* 17:00:00
 283   Mon,Fri *-*-3,1,2 *:30:45 → Mon,Fri *-*-01,02,03 *:30:45
 284        12,14,13,12:20,10,30 → *-*-* 12,13,14:10,20,30:00
 285             12..14:10,20,30 → *-*-* 12..14:10,20,30:00
 286   mon,fri *-1/2-1,3 *:30:45 → Mon,Fri *-01/2-01,03 *:30:45
 287              03-05 08:05:40 → *-03-05 08:05:40
 288                    08:05:40 → *-*-* 08:05:40
 289                       05:40 → *-*-* 05:40:00
 290      Sat,Sun 12-05 08:05:40 → Sat,Sun *-12-05 08:05:40
 291            Sat,Sun 08:05:40 → Sat,Sun *-*-* 08:05:40
 292            2003-03-05 05:40 → 2003-03-05 05:40:00
 293  05:40:23.4200004/3.1700005 → *-*-* 05:40:23.420000/3.170001
 294              2003-02..04-05 → 2003-02..04-05 00:00:00
 295        2003-03-05 05:40 UTC → 2003-03-05 05:40:00 UTC
 296                  2003-03-05 → 2003-03-05 00:00:00
 297                       03-05 → *-03-05 00:00:00
 298                      hourly → *-*-* *:00:00
 299                       daily → *-*-* 00:00:00
 300                   daily UTC → *-*-* 00:00:00 UTC
 301                     monthly → *-*-01 00:00:00
 302                      weekly → Mon *-*-* 00:00:00
 303     weekly Pacific/Auckland → Mon *-*-* 00:00:00 Pacific/Auckland
 304                      yearly → *-01-01 00:00:00
 305                    annually → *-01-01 00:00:00
 306                       *:2/3 → *-*-* *:02/3:00</programlisting>
 307
 308       <para>Calendar events are used by timer units, see
 309       <citerefentry><refentrytitle>systemd.timer</refentrytitle><manvolnum>5</manvolnum></citerefentry>
 310       for details.</para>
 311
 312       <para>Use the <command>calendar</command> command of
 313       <citerefentry><refentrytitle>systemd-analyze</refentrytitle><manvolnum>1</manvolnum></citerefentry> to validate
 314       and normalize calendar time specifications for testing purposes. The tool also calculates when a specified
 315       calendar event would occur next.</para>
 316   </refsect1>
 317
 318   <refsect1>
 319       <title>See Also</title>
 320       <para><simplelist type="inline">
 321         <member><citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
 322         <member><citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
 323         <member><citerefentry><refentrytitle>systemd.timer</refentrytitle><manvolnum>5</manvolnum></citerefentry></member>
 324         <member><citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry></member>
 325         <member><citerefentry><refentrytitle>systemd.directives</refentrytitle><manvolnum>7</manvolnum></citerefentry></member>
 326         <member><citerefentry><refentrytitle>systemd-analyze</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
 327       </simplelist></para>
 328   </refsect1>
 329
 330 </refentry>