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