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