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
  54                 events are displayed and may be specified in closely
  55                 related syntaxes.</para>
  56         </refsect1>
  57
  58         <refsect1>
  59                 <title>Displaying Time Spans</title>
  60
  61                 <para>Time spans refer to time durations. On display,
  62                 systemd will present time spans 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 Time Spans</title>
  74
  75                 <para>When parsing, systemd will accept the same
  76                 time span 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 time span allows for this.</para>
  96
  97                 <para>Examples for valid time span 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 weekday 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 weekday specification is optional,
 127                 but when the weekday 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 does not 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 weekday
 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 time span (see above) that is
 155                 prefixed with <literal>+</literal> is evaluated to the
 156                 current time plus the specified
 157                 time span. Correspondingly, a time span that is prefixed
 158                 with <literal>-</literal> is evaluated to the current
 159                 time minus the specified time span. Instead of
 160                 prefixing the time span 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 weekday while
 186                 parsing only accepts English weekday 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 weekday names, either in the abbreviated
 216                 (Wed) or non-abbreviated (Wednesday) form (case does
 217                 not matter), separated by commas. Specifying two
 218                 weekdays separated by <literal>-</literal> refers to a
 219                 range of continuous weekdays. <literal>,</literal> and
 220                 <literal>-</literal> may be combined freely.</para>
 221
 222                 <para>In the date and time specifications, any
 223                 component may be specified as <literal>*</literal> in
 224                 which case any value will match. Alternatively, each
 225                 component can be specified as list of values separated
 226                 by commas. Values may also be suffixed with
 227                 <literal>/</literal> and a repetition value, which
 228                 indicates that the value and all values plus multiples
 229                 of the repetition value are matched.</para>
 230
 231                 <para>Either time or date specification may be
 232                 omitted, in which case the current day and 00:00:00 is
 233                 implied, respectively. If the second component is not
 234                 specified <literal>:00</literal> is assumed.</para>
 235
 236                 <para>Timezone names may not be specified.</para>
 237
 238                 <para>The special expressions
 239                 <literal>hourly</literal>, <literal>daily</literal>,
 240                 <literal>monthly</literal> and <literal>weekly</literal>
 241                 may be used as calendar events which refer to
 242                 <literal>*-*-* *:00:00</literal>, <literal>*-*-*
 243                 00:00:00</literal>, <literal>*-*-01 00:00:00</literal> and
 244                 <literal>Mon *-*-* 00:00:00</literal>,
 245                 respectively.</para>
 246
 247                 <para>Examples for valid timestamps and their
 248                 normalized form:</para>
 249
 250 <programlisting>   Sat,Thu,Mon-Wed,Sat-Sun → Mon-Thu,Sat,Sun *-*-* 00:00:00
 251      Mon,Sun 12-*-* 2,1:23 → Mon,Sun 2012-*-* 01,02:23:00
 252                    Wed *-1 → Wed *-*-01 00:00:00
 253            Wed-Wed,Wed *-1 → Wed *-*-01 00:00:00
 254                 Wed, 17:48 → Wed *-*-* 17:48:00
 255 Wed-Sat,Tue 12-10-15 1:2:3 → Tue-Sat 2012-10-15 01:02:03
 256                *-*-7 0:0:0 → *-*-07 00:00:00
 257                      10-15 → *-10-15 00:00:00
 258        monday *-12-* 17:00 → Mon *-12-* 17:00:00
 259  Mon,Fri *-*-3,1,2 *:30:45 → Mon,Fri *-*-01,02,03 *:30:45
 260       12,14,13,12:20,10,30 → *-*-* 12,13,14:10,20,30:00
 261  mon,fri *-1/2-1,3 *:30:45 → Mon,Fri *-01/2-01,03 *:30:45
 262             03-05 08:05:40 → *-03-05 08:05:40
 263                   08:05:40 → *-*-* 08:05:40
 264                      05:40 → *-*-* 05:40:00
 265     Sat,Sun 12-05 08:05:40 → Sat,Sun *-12-05 08:05:40
 266           Sat,Sun 08:05:40 → Sat,Sun *-*-* 08:05:40
 267           2003-03-05 05:40 → 2003-03-05 05:40:00
 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                    monthly → *-*-01 00:00:00
 273                     weekly → Mon *-*-* 00:00:00
 274                      *:2/3 → *-*-* *:02/3:00</programlisting>
 275
 276                   <para>Calendar events are used by timer units, see
 277                   <citerefentry><refentrytitle>systemd.timer</refentrytitle><manvolnum>5</manvolnum></citerefentry>
 278                   for details.</para>
 279
 280         </refsect1>
 281
 282         <refsect1>
 283                   <title>See Also</title>
 284                   <para>
 285                           <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 286                           <citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 287                           <citerefentry><refentrytitle>systemd.timer</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 288                           <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 289                           <citerefentry><refentrytitle>systemd.directives</refentrytitle><manvolnum>7</manvolnum></citerefentry>
 290                   </para>
 291         </refsect1>
 292
 293 </refentry>