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