man/systemd.time.xml

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