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
  61     present time spans as a space-separated series of time values each
  62     suffixed by a time unit.</para>
  63
  64     <programlisting>2h 30min</programlisting>
  65
  66     <para>All specified time values are meant to be added up. The
  67     above hence refers to 150 minutes.</para>
  68   </refsect1>
  69
  70   <refsect1>
  71     <title>Parsing Time Spans</title>
  72
  73     <para>When parsing, systemd will accept the same time span syntax.
  74     Separating spaces may be omitted. The following time units are
  75     understood:</para>
  76
  77     <itemizedlist>
  78       <listitem><para>usec, us</para></listitem>
  79       <listitem><para>msec, ms</para></listitem>
  80       <listitem><para>seconds, second, sec, s</para></listitem>
  81       <listitem><para>minutes, minute, min, m</para></listitem>
  82       <listitem><para>hours, hour, hr, h</para></listitem>
  83       <listitem><para>days, day, d</para></listitem>
  84       <listitem><para>weeks, week, w</para></listitem>
  85       <listitem><para>months, month</para></listitem>
  86       <listitem><para>years, year, y</para></listitem>
  87     </itemizedlist>
  88
  89     <para>If no time unit is specified, generally seconds are assumed,
  90     but some exceptions exist and are marked as such. In a few cases
  91     <literal>ns</literal>, <literal>nsec</literal> is accepted too,
  92     where the granularity of the time span allows for this.</para>
  93
  94     <para>Examples for valid time span specifications:</para>
  95
  96     <programlisting>2 h
  97 2hours
  98 48hr
  99 1y 12month
 100 55s500ms
 101 300ms20s 5day</programlisting>
 102   </refsect1>
 103
 104   <refsect1>
 105     <title>Displaying Timestamps</title>
 106
 107     <para>Timestamps refer to specific, unique points in time. On
 108     display, systemd will format these in the local timezone as
 109     follows:</para>
 110
 111     <programlisting>Fri 2012-11-23 23:02:15 CET</programlisting>
 112
 113     <para>The weekday is printed according to the locale choice of the
 114     user.</para>
 115   </refsect1>
 116
 117   <refsect1>
 118     <title>Parsing Timestamps</title>
 119
 120     <para>When parsing, systemd will accept a similar syntax, but
 121     expects no timezone specification, unless it is given as the
 122     literal string "UTC". In this case, the time is considered in UTC,
 123     otherwise in the local timezone. The weekday specification is
 124     optional, but when the weekday is specified, it must either be in
 125     the abbreviated (<literal>Wed</literal>) or non-abbreviated
 126     (<literal>Wednesday</literal>) English language form (case does
 127     not matter), and is not subject to the locale choice of the user.
 128     Either the date, or the time part may be omitted, in which case
 129     the current date or 00:00:00, respectively, is assumed. The seconds
 130     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
 132     abbreviated (omitting the century).</para>
 133
 134     <para>A timestamp is considered invalid if a weekday is specified
 135     and the date does not actually match the specified day of the
 136     week.</para>
 137
 138     <para>When parsing, systemd will also accept a few special
 139     placeholders instead of timestamps: <literal>now</literal> may be
 140     used to refer to the current time (or of the invocation of the
 141     command that is currently executed). <literal>today</literal>,
 142     <literal>yesterday</literal>, and <literal>tomorrow</literal> refer to
 143     00:00:00 of the current day, the day before, or the next day,
 144     respectively.</para>
 145
 146     <para>When parsing, systemd will also accept relative time
 147     specifications. A time span (see above) that is prefixed with
 148     <literal>+</literal> is evaluated to the current time plus the
 149     specified time span. Correspondingly, a time span that is prefixed
 150     with <literal>-</literal> is evaluated to the current time minus
 151     the specified time span. Instead of prefixing the time span with
 152     <literal>+</literal> or <literal>-</literal>, it may also be
 153     suffixed with a space and the word <literal>left</literal> or
 154     <literal>ago</literal>.</para>
 155
 156     <para>Finally, a timespan prefixed with <literal>@</literal> is
 157     evaluated relative to the UNIX time epoch 1st Jan, 1970,
 158     00:00.</para>
 159
 160     <para>Examples for valid timestamps and their normalized form
 161     (assuming the current time was 2012-11-23 18:15:22 and the timezone
 162     was UTC+8, for example TZ=Asia/Shanghai):</para>
 163
 164     <programlisting>Fri 2012-11-23 11:12:13 → Fri 2012-11-23 11:12:13
 165     2012-11-23 11:12:13 → Fri 2012-11-23 11:12:13
 166 2012-11-23 11:12:13 UTC → Fri 2012-11-23 19:12:13
 167              2012-11-23 → Fri 2012-11-23 00:00:00
 168                12-11-23 → Fri 2012-11-23 00:00:00
 169                11:12:13 → Fri 2012-11-23 11:12:13
 170        11:12:13.9900009 → Fri 2012-11-23 11:12:13
 171                           format_timestamp_us: Fri 2012-11-23 11:12:13.990000
 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                +3h30min → Fri 2012-11-23 21:45:22
 179            +3h30min UTC → -EINVAL
 180                     -5s → Fri 2012-11-23 18:15:17
 181               11min ago → Fri 2012-11-23 18:04:22
 182           11min ago UTC → -EINVAL
 183             @1395716396 → Tue 2014-03-25 03:59:56</programlisting>
 184
 185     <para>Note that timestamps printed by systemd will not be parsed
 186     correctly by systemd, as the timezone specification is not
 187     accepted, and printing timestamps is subject to locale settings
 188     for the weekday, while parsing only accepts English weekday
 189     names.</para>
 190
 191     <para>In some cases, systemd will display a relative timestamp
 192     (relative to the current time, or the time of invocation of the
 193     command) instead or in addition to an absolute timestamp as
 194     described above. A relative timestamp is formatted as
 195     follows:</para>
 196
 197     <para>2 months 5 days ago</para>
 198
 199     <para>Note that any relative timestamp will also parse correctly
 200     where a timestamp is expected. (see above)</para>
 201   </refsect1>
 202
 203   <refsect1>
 204     <title>Calendar Events</title>
 205
 206     <para>Calendar events may be used to refer to one or more points
 207     in time in a single expression. They form a superset of the
 208     absolute timestamps explained above:</para>
 209
 210     <programlisting>Thu,Fri 2012-*-1,5 11:12:13</programlisting>
 211
 212     <para>The above refers to 11:12:13 of the first or fifth day of
 213     any month of the year 2012, but only if that day is a Thursday or
 214     Friday.</para>
 215
 216     <para>The weekday specification is optional. If specified, it
 217     should consist of one or more English language weekday names,
 218     either in the abbreviated (Wed) or non-abbreviated (Wednesday)
 219     form (case does not matter), separated by commas. Specifying two
 220     weekdays separated by <literal>-</literal> refers to a range of
 221     continuous weekdays. <literal>,</literal> and <literal>-</literal>
 222     may be combined freely.</para>
 223
 224     <para>In the date and time specifications, any component may be
 225     specified as <literal>*</literal> in which case any value will
 226     match. Alternatively, each component can be specified as a list of
 227     values separated by commas. Values may also be suffixed with
 228     <literal>/</literal> and a repetition value, which indicates that
 229     the value and all values plus multiples of the repetition value
 230     are matched.</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>A timezone specification is not expected, unless it is given
 238     as the literal string "UTC", similarly to timestamps.</para>
 239
 240     <para>The special expressions
 241     <literal>minutely</literal>,
 242     <literal>hourly</literal>, <literal>daily</literal>,
 243     <literal>monthly</literal>, <literal>weekly</literal>,
 244     <literal>yearly</literal>,
 245     <literal>quarterly</literal>,
 246     <literal>semiannually</literal> may be used as
 247     calendar events which refer to
 248     <literal>*-*-* *:*:00</literal>,
 249     <literal>*-*-* *:00:00</literal>,
 250     <literal>*-*-* 00:00:00</literal>,
 251     <literal>*-*-01 00:00:00</literal>,
 252     <literal>Mon *-*-* 00:00:00</literal>,
 253     <literal>*-01-01 00:00:00</literal>,
 254     <literal>*-01,04,07,10-01 00:00:00</literal> and
 255     <literal>*-01,07-01 00:00:00</literal>, respectively.
 256     </para>
 257
 258     <para>Examples for valid timestamps and their
 259     normalized form:</para>
 260
 261 <programlisting>   Sat,Thu,Mon-Wed,Sat-Sun → Mon-Thu,Sat,Sun *-*-* 00:00:00
 262      Mon,Sun 12-*-* 2,1:23 → Mon,Sun 2012-*-* 01,02:23:00
 263                    Wed *-1 → Wed *-*-01 00:00:00
 264            Wed-Wed,Wed *-1 → Wed *-*-01 00:00:00
 265                 Wed, 17:48 → Wed *-*-* 17:48:00
 266 Wed-Sat,Tue 12-10-15 1:2:3 → Tue-Sat 2012-10-15 01:02:03
 267                *-*-7 0:0:0 → *-*-07 00:00:00
 268                      10-15 → *-10-15 00:00:00
 269        monday *-12-* 17:00 → Mon *-12-* 17:00:00
 270  Mon,Fri *-*-3,1,2 *:30:45 → Mon,Fri *-*-01,02,03 *:30:45
 271       12,14,13,12:20,10,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       2003-03-05 05:40 UTC → 2003-03-05 05:40:00 UTC
 280                 2003-03-05 → 2003-03-05 00:00:00
 281                      03-05 → *-03-05 00:00:00
 282                     hourly → *-*-* *:00:00
 283                      daily → *-*-* 00:00:00
 284                  daily UTC → *-*-* 00:00:00 UTC
 285                    monthly → *-*-01 00:00:00
 286                     weekly → Mon *-*-* 00:00:00
 287                     yearly → *-01-01 00:00:00
 288                   annually → *-01-01 00:00:00
 289                      *:2/3 → *-*-* *:02/3:00</programlisting>
 290
 291       <para>Calendar events are used by timer units, see
 292       <citerefentry><refentrytitle>systemd.timer</refentrytitle><manvolnum>5</manvolnum></citerefentry>
 293       for details.</para>
 294
 295   </refsect1>
 296
 297   <refsect1>
 298       <title>See Also</title>
 299       <para>
 300         <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 301         <citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 302         <citerefentry><refentrytitle>systemd.timer</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 303         <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 304         <citerefentry><refentrytitle>systemd.directives</refentrytitle><manvolnum>7</manvolnum></citerefentry>
 305       </para>
 306   </refsect1>
 307
 308 </refentry>