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