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