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