man/systemd.time.xml

   1 <?xml version='1.0'?> <!--*-nxml-*-->
   2 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
   3   "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
   4
   5 <!--
   6   SPDX-License-Identifier: LGPL-2.1+
   7
   8   This file is part of systemd.
   9
  10   Copyright 2010 Lennart Poettering
  11 -->
  12
  13 <refentry id="systemd.time">
  14
  15   <refentryinfo>
  16     <title>systemd.time</title>
  17     <productname>systemd</productname>
  18
  19     <authorgroup>
  20       <author>
  21         <contrib>Developer</contrib>
  22         <firstname>Lennart</firstname>
  23         <surname>Poettering</surname>
  24         <email>lennart@poettering.net</email>
  25       </author>
  26     </authorgroup>
  27   </refentryinfo>
  28
  29   <refmeta>
  30     <refentrytitle>systemd.time</refentrytitle>
  31     <manvolnum>7</manvolnum>
  32   </refmeta>
  33
  34   <refnamediv>
  35     <refname>systemd.time</refname>
  36     <refpurpose>Time and date specifications</refpurpose>
  37   </refnamediv>
  38
  39   <refsect1>
  40     <title>Description</title>
  41
  42     <para>In systemd, timestamps, time spans, and calendar events are
  43     displayed and may be specified in closely related syntaxes.</para>
  44   </refsect1>
  45
  46   <refsect1>
  47     <title>Displaying Time Spans</title>
  48
  49     <para>Time spans refer to time durations. On display, systemd will present time spans as a space-separated series
  50     of time values each suffixed by a time unit. Example:</para>
  51
  52     <programlisting>2h 30min</programlisting>
  53
  54     <para>All specified time values are meant to be added up. The above hence refers to 150 minutes. Display is
  55     locale-independent, only English names for the time units are used.</para>
  56   </refsect1>
  57
  58   <refsect1>
  59     <title>Parsing Time Spans</title>
  60
  61     <para>When parsing, systemd will accept the same time span syntax.
  62     Separating spaces may be omitted. The following time units are
  63     understood:</para>
  64
  65     <itemizedlist>
  66       <listitem><para>usec, us</para></listitem>
  67       <listitem><para>msec, ms</para></listitem>
  68       <listitem><para>seconds, second, sec, s</para></listitem>
  69       <listitem><para>minutes, minute, min, m</para></listitem>
  70       <listitem><para>hours, hour, hr, h</para></listitem>
  71       <listitem><para>days, day, d</para></listitem>
  72       <listitem><para>weeks, week, w</para></listitem>
  73       <listitem><para>months, month, M (defined as 30.44 days)</para></listitem>
  74       <listitem><para>years, year, y (defined as 365.25 days)</para></listitem>
  75     </itemizedlist>
  76
  77     <para>If no time unit is specified, generally seconds are assumed, but some exceptions exist and are marked as
  78     such. In a few cases <literal>ns</literal>, <literal>nsec</literal> is accepted too, where the granularity of the
  79     time span permits this. Parsing is generally locale-independent, non-English names for the time units are not
  80     accepted.</para>
  81
  82     <para>Examples for valid time span specifications:</para>
  83
  84     <programlisting>2 h
  85 2hours
  86 48hr
  87 1y 12month
  88 55s500ms
  89 300ms20s 5day</programlisting>
  90   </refsect1>
  91
  92   <refsect1>
  93     <title>Displaying Timestamps</title>
  94
  95     <para>Timestamps refer to specific, unique points in time. On
  96     display, systemd will format these in the local timezone as
  97     follows:</para>
  98
  99     <programlisting>Fri 2012-11-23 23:02:15 CET</programlisting>
 100
 101     <para>The weekday is printed in the abbreviated English language form. The formatting is locale-independent.</para>
 102
 103     <para>In some cases timestamps are shown in the UTC timezone instead of the local timezone, which is indicated via
 104     the <literal>UTC</literal> timezone specifier in the output.</para>
 105
 106     <para>In some cases timestamps are shown with microsecond granularity. In this case the sub-second remainder is
 107     separated by a full stop from the seconds component.</para>
 108   </refsect1>
 109
 110   <refsect1>
 111     <title>Parsing Timestamps</title>
 112
 113     <para>When parsing, systemd will accept a similar syntax, but expects no timezone specification, unless it is given
 114     as the literal string <literal>UTC</literal> (for the UTC timezone), or is specified to be the locally configured
 115     timezone, or the timezone name in the IANA timezone database format. The complete list of timezones
 116     supported on your system can be obtained using the <literal>timedatectl list-timezones</literal>
 117     (see <citerefentry><refentrytitle>timedatectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>).
 118     Using IANA format is recommended over local timezone names, as less prone to errors (eg: with local timezone it's possible to
 119     specify daylight saving time in winter, while it's incorrect). The weekday specification is optional, but when
 120     the weekday is specified, it must either be in the abbreviated (<literal>Wed</literal>) or non-abbreviated
 121     (<literal>Wednesday</literal>) English language form (case does not matter), and is not subject to the locale
 122     choice of the user.  Either the date, or the time part may be omitted, in which case the current date or 00:00:00,
 123     respectively, is assumed. The seconds component of the time may also be omitted, in which case ":00" is
 124     assumed. Year numbers may be specified in full or may be abbreviated (omitting the century).</para>
 125
 126     <para>A timestamp is considered invalid if a weekday is specified and the date does not match the specified day of
 127     the week.</para>
 128
 129     <para>When parsing, systemd will also accept a few special
 130     placeholders instead of timestamps: <literal>now</literal> may be
 131     used to refer to the current time (or of the invocation of the
 132     command that is currently executed). <literal>today</literal>,
 133     <literal>yesterday</literal>, and <literal>tomorrow</literal> refer to
 134     00:00:00 of the current day, the day before, or the next day,
 135     respectively.</para>
 136
 137     <para>When parsing, systemd will also accept relative time
 138     specifications. A time span (see above) that is prefixed with
 139     <literal>+</literal> is evaluated to the current time plus the
 140     specified time span. Correspondingly, a time span that is prefixed
 141     with <literal>-</literal> is evaluated to the current time minus
 142     the specified time span. Instead of prefixing the time span with
 143     <literal>+</literal> or <literal>-</literal>, it may also be
 144     suffixed with a space and the word <literal>left</literal> or
 145     <literal>ago</literal>.</para>
 146
 147     <para>Finally, a timespan prefixed with <literal>@</literal> is
 148     evaluated relative to the UNIX time epoch 1st Jan, 1970,
 149     00:00.</para>
 150
 151     <para>Examples for valid timestamps and their normalized form
 152     (assuming the current time was 2012-11-23 18:15:22 and the timezone
 153     was UTC+8, for example TZ=Asia/Shanghai):</para>
 154
 155     <programlisting>  Fri 2012-11-23 11:12:13 → Fri 2012-11-23 11:12:13
 156       2012-11-23 11:12:13 → Fri 2012-11-23 11:12:13
 157   2012-11-23 11:12:13 UTC → Fri 2012-11-23 19:12:13
 158                2012-11-23 → Fri 2012-11-23 00:00:00
 159                  12-11-23 → Fri 2012-11-23 00:00:00
 160                  11:12:13 → Fri 2012-11-23 11:12:13
 161                     11:12 → Fri 2012-11-23 11:12:00
 162                       now → Fri 2012-11-23 18:15:22
 163                     today → Fri 2012-11-23 00:00:00
 164                 today UTC → Fri 2012-11-23 16:00:00
 165                 yesterday → Fri 2012-11-22 00:00:00
 166                  tomorrow → Fri 2012-11-24 00:00:00
 167 tomorrow Pacific/Auckland → Thu 2012-11-23 19:00:00
 168                  +3h30min → Fri 2012-11-23 21:45:22
 169                       -5s → Fri 2012-11-23 18:15:17
 170                 11min ago → Fri 2012-11-23 18:04:22
 171               @1395716396 → Tue 2014-03-25 03:59:56</programlisting>
 172
 173     <para>Note that timestamps displayed by remote systems with a non-matching timezone are usually not parsable
 174     locally, as the timezone component is not understood (unless it happens to be <literal>UTC</literal>).</para>
 175
 176     <para>Timestamps may also be specified with microsecond granularity. The sub-second remainder is expected separated
 177     by a full stop from the seconds component. Example:</para>
 178
 179     <programlisting>2014-03-25 03:59:56.654563</programlisting>
 180
 181     <para>In some cases, systemd will display a relative timestamp (relative to the current time, or the time of
 182     invocation of the command) instead of or in addition to an absolute timestamp as described above. A relative
 183     timestamp is formatted as follows:</para>
 184
 185     <programlisting>2 months 5 days ago</programlisting>
 186
 187     <para>Note that a relative timestamp is also accepted where a timestamp is expected (see above).</para>
 188   </refsect1>
 189
 190   <refsect1>
 191     <title>Calendar Events</title>
 192
 193     <para>Calendar events may be used to refer to one or more points
 194     in time in a single expression. They form a superset of the
 195     absolute timestamps explained above:</para>
 196
 197     <programlisting>Thu,Fri 2012-*-1,5 11:12:13</programlisting>
 198
 199     <para>The above refers to 11:12:13 of the first or fifth day of
 200     any month of the year 2012, but only if that day is a Thursday or
 201     Friday.</para>
 202
 203     <para>The weekday specification is optional. If specified, it
 204     should consist of one or more English language weekday names,
 205     either in the abbreviated (Wed) or non-abbreviated (Wednesday)
 206     form (case does not matter), separated by commas. Specifying two
 207     weekdays separated by <literal>..</literal> refers to a range of
 208     continuous weekdays. <literal>,</literal> and <literal>..</literal>
 209     may be combined freely.</para>
 210
 211     <para>In the date and time specifications, any component may be
 212     specified as <literal>*</literal> in which case any value will
 213     match. Alternatively, each component can be specified as a list of
 214     values separated by commas. Values may be suffixed with
 215     <literal>/</literal> and a repetition value, which indicates that
 216     the value itself and the value plus all multiples of the repetition value
 217     are matched.  Two values separated by <literal>..</literal> may be used
 218     to indicate a range of values; ranges may also be followed with
 219     <literal>/</literal> and a repetition value.</para>
 220
 221     <para>A date specification may use <literal>~</literal> to indicate the
 222     last day(s) in a month. For example, <literal>*-02~03</literal> means
 223     "the third last day in February," and <literal>Mon *-05~07/1</literal>
 224     means "the last Monday in May."</para>
 225
 226     <para>The seconds component may contain decimal fractions both in
 227     the value and the repetition. All fractions are rounded to 6
 228     decimal places.</para>
 229
 230     <para>Either time or date specification may be omitted, in which
 231     case the current day and 00:00:00 is implied, respectively. If the
 232     second component is not specified, <literal>:00</literal> is
 233     assumed.</para>
 234
 235     <para>Timezone can be specified as the literal string <literal>UTC</literal>, or
 236     the local timezone, similar to the supported syntax of timestamps (see above), or the timezone
 237     in the IANA timezone database format (also see above).</para>
 238
 239   <para>The following special expressions may be used as shorthands for longer normalized forms:</para>
 240
 241     <programlisting>    minutely → *-*-* *:*:00
 242       hourly → *-*-* *:00:00
 243        daily → *-*-* 00:00:00
 244      monthly → *-*-01 00:00:00
 245       weekly → Mon *-*-* 00:00:00
 246       yearly → *-01-01 00:00:00
 247    quarterly → *-01,04,07,10-01 00:00:00
 248 semiannually → *-01,07-01 00:00:00
 249    </programlisting>
 250
 251     <para>Examples for valid timestamps and their
 252     normalized form:</para>
 253
 254 <programlisting>  Sat,Thu,Mon..Wed,Sat..Sun → Mon..Thu,Sat,Sun *-*-* 00:00:00
 255       Mon,Sun 12-*-* 2,1:23 → Mon,Sun 2012-*-* 01,02:23:00
 256                     Wed *-1 → Wed *-*-01 00:00:00
 257            Wed..Wed,Wed *-1 → Wed *-*-01 00:00:00
 258                  Wed, 17:48 → Wed *-*-* 17:48:00
 259 Wed..Sat,Tue 12-10-15 1:2:3 → Tue..Sat 2012-10-15 01:02:03
 260                 *-*-7 0:0:0 → *-*-07 00:00:00
 261                       10-15 → *-10-15 00:00:00
 262         monday *-12-* 17:00 → Mon *-12-* 17:00:00
 263   Mon,Fri *-*-3,1,2 *:30:45 → Mon,Fri *-*-01,02,03 *:30:45
 264        12,14,13,12:20,10,30 → *-*-* 12,13,14:10,20,30:00
 265             12..14:10,20,30 → *-*-* 12..14:10,20,30:00
 266   mon,fri *-1/2-1,3 *:30:45 → Mon,Fri *-01/2-01,03 *:30:45
 267              03-05 08:05:40 → *-03-05 08:05:40
 268                    08:05:40 → *-*-* 08:05:40
 269                       05:40 → *-*-* 05:40:00
 270      Sat,Sun 12-05 08:05:40 → Sat,Sun *-12-05 08:05:40
 271            Sat,Sun 08:05:40 → Sat,Sun *-*-* 08:05:40
 272            2003-03-05 05:40 → 2003-03-05 05:40:00
 273  05:40:23.4200004/3.1700005 → *-*-* 05:40:23.420000/3.170001
 274              2003-02..04-05 → 2003-02..04-05 00:00:00
 275        2003-03-05 05:40 UTC → 2003-03-05 05:40:00 UTC
 276                  2003-03-05 → 2003-03-05 00:00:00
 277                       03-05 → *-03-05 00:00:00
 278                      hourly → *-*-* *:00:00
 279                       daily → *-*-* 00:00:00
 280                   daily UTC → *-*-* 00:00:00 UTC
 281                     monthly → *-*-01 00:00:00
 282                      weekly → Mon *-*-* 00:00:00
 283     weekly Pacific/Auckland → Mon *-*-* 00:00:00 Pacific/Auckland
 284                      yearly → *-01-01 00:00:00
 285                    annually → *-01-01 00:00:00
 286                       *:2/3 → *-*-* *:02/3:00</programlisting>
 287
 288       <para>Calendar events are used by timer units, see
 289       <citerefentry><refentrytitle>systemd.timer</refentrytitle><manvolnum>5</manvolnum></citerefentry>
 290       for details.</para>
 291
 292       <para>Use the <command>calendar</command> command of
 293       <citerefentry><refentrytitle>systemd-analyze</refentrytitle><manvolnum>1</manvolnum></citerefentry> to validate
 294       and normalize calendar time specifications for testing purposes. The tool also calculates when a specified
 295       calendar event would elapse next.</para>
 296   </refsect1>
 297
 298   <refsect1>
 299       <title>See Also</title>
 300       <para>
 301         <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 302         <citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 303         <citerefentry><refentrytitle>systemd.timer</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 304         <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 305         <citerefentry><refentrytitle>systemd.directives</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
 306         <citerefentry><refentrytitle>systemd-analyze</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 307       </para>
 308   </refsect1>
 309
 310 </refentry>