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. Other timezones than the local and UTC are not supported. The weekday specification is optional, but when
 127     the weekday is specified, it must either be in the abbreviated (<literal>Wed</literal>) or non-abbreviated
 128     (<literal>Wednesday</literal>) English language form (case does not matter), and is not subject to the locale
 129     choice of the user.  Either the date, or the time part may be omitted, in which case the current date or 00:00:00,
 130     respectively, is assumed. The seconds component of the time may also be omitted, in which case ":00" is
 131     assumed. Year numbers may be specified in full or may be abbreviated (omitting the century).</para>
 132
 133     <para>A timestamp is considered invalid if a weekday is specified and the date does not match the specified day of
 134     the week.</para>
 135
 136     <para>When parsing, systemd will also accept a few special
 137     placeholders instead of timestamps: <literal>now</literal> may be
 138     used to refer to the current time (or of the invocation of the
 139     command that is currently executed). <literal>today</literal>,
 140     <literal>yesterday</literal>, and <literal>tomorrow</literal> refer to
 141     00:00:00 of the current day, the day before, or the next day,
 142     respectively.</para>
 143
 144     <para>When parsing, systemd will also accept relative time
 145     specifications. A time span (see above) that is prefixed with
 146     <literal>+</literal> is evaluated to the current time plus the
 147     specified time span. Correspondingly, a time span that is prefixed
 148     with <literal>-</literal> is evaluated to the current time minus
 149     the specified time span. Instead of prefixing the time span with
 150     <literal>+</literal> or <literal>-</literal>, it may also be
 151     suffixed with a space and the word <literal>left</literal> or
 152     <literal>ago</literal>.</para>
 153
 154     <para>Finally, a timespan prefixed with <literal>@</literal> is
 155     evaluated relative to the UNIX time epoch 1st Jan, 1970,
 156     00:00.</para>
 157
 158     <para>Examples for valid timestamps and their normalized form
 159     (assuming the current time was 2012-11-23 18:15:22 and the timezone
 160     was UTC+8, for example TZ=Asia/Shanghai):</para>
 161
 162     <programlisting>Fri 2012-11-23 11:12:13 → Fri 2012-11-23 11:12:13
 163     2012-11-23 11:12:13 → Fri 2012-11-23 11:12:13
 164 2012-11-23 11:12:13 UTC → Fri 2012-11-23 19:12:13
 165              2012-11-23 → Fri 2012-11-23 00:00:00
 166                12-11-23 → Fri 2012-11-23 00:00:00
 167                11:12:13 → Fri 2012-11-23 11:12:13
 168                   11:12 → Fri 2012-11-23 11:12:00
 169                     now → Fri 2012-11-23 18:15:22
 170                   today → Fri 2012-11-23 00:00:00
 171               today UTC → Fri 2012-11-23 16:00:00
 172               yesterday → Fri 2012-11-22 00:00:00
 173                tomorrow → Fri 2012-11-24 00:00:00
 174                +3h30min → Fri 2012-11-23 21:45:22
 175                     -5s → Fri 2012-11-23 18:15:17
 176               11min ago → Fri 2012-11-23 18:04:22
 177             @1395716396 → Tue 2014-03-25 03:59:56</programlisting>
 178
 179     <para>Note that timestamps displayed by remote systems with a non-matching timezone are usually not parsable
 180     locally, as the timezone component is not understood (unless it happens to be <literal>UTC</literal>).</para>
 181
 182     <para>Timestamps may also be specified with microsecond granularity. The sub-second remainder is expected separated
 183     by a full stop from the seconds component. Example:</para>
 184
 185     <programlisting>2014-03-25 03:59:56.654563</programlisting>
 186
 187     <para>In some cases, systemd will display a relative timestamp (relative to the current time, or the time of
 188     invocation of the command) instead of or in addition to an absolute timestamp as described above. A relative
 189     timestamp is formatted as follows:</para>
 190
 191     <programlisting>2 months 5 days ago</programlisting>
 192
 193     <para>Note that a relative timestamp is also accepted where a timestamp is expected (see above).</para>
 194   </refsect1>
 195
 196   <refsect1>
 197     <title>Calendar Events</title>
 198
 199     <para>Calendar events may be used to refer to one or more points
 200     in time in a single expression. They form a superset of the
 201     absolute timestamps explained above:</para>
 202
 203     <programlisting>Thu,Fri 2012-*-1,5 11:12:13</programlisting>
 204
 205     <para>The above refers to 11:12:13 of the first or fifth day of
 206     any month of the year 2012, but only if that day is a Thursday or
 207     Friday.</para>
 208
 209     <para>The weekday specification is optional. If specified, it
 210     should consist of one or more English language weekday names,
 211     either in the abbreviated (Wed) or non-abbreviated (Wednesday)
 212     form (case does not matter), separated by commas. Specifying two
 213     weekdays separated by <literal>..</literal> refers to a range of
 214     continuous weekdays. <literal>,</literal> and <literal>..</literal>
 215     may be combined freely.</para>
 216
 217     <para>In the date and time specifications, any component may be
 218     specified as <literal>*</literal> in which case any value will
 219     match. Alternatively, each component can be specified as a list of
 220     values separated by commas. Values may also be suffixed with
 221     <literal>/</literal> and a repetition value, which indicates that
 222     the value itself and the value plus all multiples of the repetition value
 223     are matched.  Each component may also contain a range of values
 224     separated by <literal>..</literal>.</para>
 225
 226     <para>The seconds component may contain decimal fractions both in
 227     the value and the repetition. All fractions are rounded to 6
 228     decimal places.</para>
 229
 230     <para>Either time or date specification may be omitted, in which
 231     case the current day and 00:00:00 is implied, respectively. If the
 232     second component is not specified, <literal>:00</literal> is
 233     assumed.</para>
 234
 235     <para>A timezone specification is not expected, unless it is given as the literal string <literal>UTC</literal>, or
 236     the local timezone, similar to the supported syntax of timestamps (see above). Non-local timezones except for UTC
 237     are not supported.</para>
 238
 239     <para>The special expressions
 240     <literal>minutely</literal>,
 241     <literal>hourly</literal>, <literal>daily</literal>,
 242     <literal>monthly</literal>, <literal>weekly</literal>,
 243     <literal>yearly</literal>,
 244     <literal>quarterly</literal>,
 245     <literal>semiannually</literal> may be used as
 246     calendar events which refer to
 247     <literal>*-*-* *:*:00</literal>,
 248     <literal>*-*-* *:00:00</literal>,
 249     <literal>*-*-* 00:00:00</literal>,
 250     <literal>*-*-01 00:00:00</literal>,
 251     <literal>Mon *-*-* 00:00:00</literal>,
 252     <literal>*-01-01 00:00:00</literal>,
 253     <literal>*-01,04,07,10-01 00:00:00</literal> and
 254     <literal>*-01,07-01 00:00:00</literal>, respectively.
 255     </para>
 256
 257     <para>Examples for valid timestamps and their
 258     normalized form:</para>
 259
 260 <programlisting>  Sat,Thu,Mon..Wed,Sat..Sun → Mon..Thu,Sat,Sun *-*-* 00:00:00
 261       Mon,Sun 12-*-* 2,1:23 → Mon,Sun 2012-*-* 01,02:23:00
 262                     Wed *-1 → Wed *-*-01 00:00:00
 263            Wed..Wed,Wed *-1 → Wed *-*-01 00:00:00
 264                  Wed, 17:48 → Wed *-*-* 17:48:00
 265 Wed..Sat,Tue 12-10-15 1:2:3 → Tue..Sat 2012-10-15 01:02:03
 266                 *-*-7 0:0:0 → *-*-07 00:00:00
 267                       10-15 → *-10-15 00:00:00
 268         monday *-12-* 17:00 → Mon *-12-* 17:00:00
 269   Mon,Fri *-*-3,1,2 *:30:45 → Mon,Fri *-*-01,02,03 *:30:45
 270        12,14,13,12:20,10,30 → *-*-* 12,13,14:10,20,30:00
 271             12..14:10,20,30 → *-*-* 12,13,14:10,20,30:00
 272   mon,fri *-1/2-1,3 *:30:45 → Mon,Fri *-01/2-01,03 *:30:45
 273              03-05 08:05:40 → *-03-05 08:05:40
 274                    08:05:40 → *-*-* 08:05:40
 275                       05:40 → *-*-* 05:40:00
 276      Sat,Sun 12-05 08:05:40 → Sat,Sun *-12-05 08:05:40
 277            Sat,Sun 08:05:40 → Sat,Sun *-*-* 08:05:40
 278            2003-03-05 05:40 → 2003-03-05 05:40:00
 279  05:40:23.4200004/3.1700005 → 05:40:23.420000/3.170001
 280              2003-02..04-05 → 2003-02,03,04-05 00:00:00
 281        2003-03-05 05:40 UTC → 2003-03-05 05:40:00 UTC
 282                  2003-03-05 → 2003-03-05 00:00:00
 283                       03-05 → *-03-05 00:00:00
 284                      hourly → *-*-* *:00:00
 285                       daily → *-*-* 00:00:00
 286                   daily UTC → *-*-* 00:00:00 UTC
 287                     monthly → *-*-01 00:00:00
 288                      weekly → Mon *-*-* 00:00:00
 289                      yearly → *-01-01 00:00:00
 290                    annually → *-01-01 00:00:00
 291                       *:2/3 → *-*-* *:02/3:00</programlisting>
 292
 293       <para>Calendar events are used by timer units, see
 294       <citerefentry><refentrytitle>systemd.timer</refentrytitle><manvolnum>5</manvolnum></citerefentry>
 295       for details.</para>
 296
 297   </refsect1>
 298
 299   <refsect1>
 300       <title>See Also</title>
 301       <para>
 302         <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 303         <citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 304         <citerefentry><refentrytitle>systemd.timer</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 305         <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 306         <citerefentry><refentrytitle>systemd.directives</refentrytitle><manvolnum>7</manvolnum></citerefentry>
 307       </para>
 308   </refsect1>
 309
 310 </refentry>