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 time
 157                 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> or
 161                 <literal>-</literal>, it may also be suffixed with a
 162                 space and the word <literal>left</literal> or
 163                 <literal>ago</literal>.</para>
 164
 165                 <para>Finally, a timespan prefixed with
 166                 <literal>@</literal> is evaluated relative to the UNIX
 167                 time epoch 1st Jan, 1970, 00:00.</para>
 168
 169                 <para>Examples for valid timestamps and their
 170                 normalized form (assuming the current time was
 171                 2012-11-23 18:15:22):</para>
 172
 173                 <programlisting>Fri 2012-11-23 11:12:13 → Fri 2012-11-23 11:12:13
 174     2012-11-23 11:12:13 → Fri 2012-11-23 11:12:13
 175              2012-11-23 → Fri 2012-11-23 00:00:00
 176                12-11-23 → Fri 2012-11-23 00:00:00
 177                11:12:13 → Fri 2012-11-23 11:12:13
 178                   11:12 → Fri 2012-11-23 11:12:00
 179                     now → Fri 2012-11-23 18:15:22
 180                   today → Fri 2012-11-23 00:00:00
 181               yesterday → Fri 2012-11-22 00:00:00
 182                tomorrow → Fri 2012-11-24 00:00:00
 183                +3h30min → Fri 2012-11-23 21:45:22
 184                     -5s → Fri 2012-11-23 18:15:17
 185               11min ago → Fri 2012-11-23 18:04:22
 186             @1395716396 → Tue 2014-03-25 03:59:56</programlisting>
 187
 188                 <para>Note that timestamps printed by systemd will not
 189                 be parsed correctly by systemd, as the timezone
 190                 specification is not accepted, and printing timestamps
 191                 is subject to locale settings for the weekday while
 192                 parsing only accepts English weekday names.</para>
 193
 194                 <para>In some cases, systemd will display a relative
 195                 timestamp (relative to the current time, or the time
 196                 of invocation of the command) instead or in addition
 197                 to an absolute timestamp as described above. A
 198                 relative timestamp is formatted as follows:</para>
 199
 200                 <para>2 months 5 days ago</para>
 201
 202                 <para>Note that any relative timestamp will also parse
 203                 correctly where a timestamp is expected. (see above)</para>
 204         </refsect1>
 205
 206         <refsect1>
 207                 <title>Calendar Events</title>
 208
 209                 <para>Calendar events may be used to refer to one or
 210                 more points in time in a single expression. They form
 211                 a superset of the absolute timestamps explained above:</para>
 212
 213                 <programlisting>Thu,Fri 2012-*-1,5 11:12:13</programlisting>
 214
 215                 <para>The above refers to 11:12:13 of the first or
 216                 fifth day of any month of the year 2012, given that it
 217                 is a Thursday or Friday.</para>
 218
 219                 <para>The weekday specification is optional. If
 220                 specified, it should consist of one or more English
 221                 language weekday names, either in the abbreviated
 222                 (Wed) or non-abbreviated (Wednesday) form (case does
 223                 not matter), separated by commas. Specifying two
 224                 weekdays separated by <literal>-</literal> refers to a
 225                 range of continuous weekdays. <literal>,</literal> and
 226                 <literal>-</literal> may be combined freely.</para>
 227
 228                 <para>In the date and time specifications, any
 229                 component may be specified as <literal>*</literal> in
 230                 which case any value will match. Alternatively, each
 231                 component can be specified as a list of values separated
 232                 by commas. Values may also be suffixed with
 233                 <literal>/</literal> and a repetition value, which
 234                 indicates that the value and all values plus multiples
 235                 of the repetition value are matched.</para>
 236
 237                 <para>Either time or date specification may be
 238                 omitted, in which case the current day and 00:00:00 is
 239                 implied, respectively. If the second component is not
 240                 specified, <literal>:00</literal> is assumed.</para>
 241
 242                 <para>Timezone names may not be specified.</para>
 243
 244                 <para>The special expressions
 245                 <literal>hourly</literal>, <literal>daily</literal>,
 246                 <literal>monthly</literal> and <literal>weekly</literal>
 247                 may be used as calendar events which refer to
 248                 <literal>*-*-* *:00:00</literal>, <literal>*-*-*
 249                 00:00:00</literal>, <literal>*-*-01 00:00:00</literal> and
 250                 <literal>Mon *-*-* 00:00:00</literal>,
 251                 respectively.</para>
 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  mon,fri *-1/2-1,3 *:30:45 → Mon,Fri *-01/2-01,03 *:30:45
 268             03-05 08:05:40 → *-03-05 08:05:40
 269                   08:05:40 → *-*-* 08:05:40
 270                      05:40 → *-*-* 05:40:00
 271     Sat,Sun 12-05 08:05:40 → Sat,Sun *-12-05 08:05:40
 272           Sat,Sun 08:05:40 → Sat,Sun *-*-* 08:05:40
 273           2003-03-05 05:40 → 2003-03-05 05:40:00
 274                 2003-03-05 → 2003-03-05 00:00:00
 275                      03-05 → *-03-05 00:00:00
 276                     hourly → *-*-* *:00:00
 277                      daily → *-*-* 00:00:00
 278                    monthly → *-*-01 00:00:00
 279                     weekly → Mon *-*-* 00:00:00
 280                      *:2/3 → *-*-* *:02/3:00</programlisting>
 281
 282                   <para>Calendar events are used by timer units, see
 283                   <citerefentry><refentrytitle>systemd.timer</refentrytitle><manvolnum>5</manvolnum></citerefentry>
 284                   for details.</para>
 285
 286         </refsect1>
 287
 288         <refsect1>
 289                   <title>See Also</title>
 290                   <para>
 291                           <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 292                           <citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 293                           <citerefentry><refentrytitle>systemd.timer</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 294                           <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 295                           <citerefentry><refentrytitle>systemd.directives</refentrytitle><manvolnum>7</manvolnum></citerefentry>
 296                   </para>
 297         </refsect1>
 298
 299 </refentry>