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