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 timestamp syntax,
 121     but excluding any timezone specification (this limitation might be
 122     removed eventually). The weekday specification is optional, but
 123     when the weekday is specified it must either be in the abbreviated
 124     (<literal>Wed</literal>) or non-abbreviated
 125     (<literal>Wednesday</literal>) English language form (case does
 126     not matter), and is not subject to the locale choice of the user.
 127     Either the date, or the time part may be omitted, in which case
 128     the current date or 00:00:00, resp., is assumed. The seconds
 129     component of the time may also be omitted, in which case ":00" is
 130     assumed. Year numbers may be specified in full or may be
 131     abbreviated (omitting the century).</para>
 132
 133     <para>A timestamp is considered invalid if a weekday is specified
 134     and the date does not actually match the specified day of the
 135     week.</para>
 136
 137     <para>When parsing, systemd will also accept a few special
 138     placeholders instead of timestamps: <literal>now</literal> may be
 139     used to refer to the current time (or of the invocation of the
 140     command that is currently executed). <literal>today</literal>,
 141     <literal>yesterday</literal>, <literal>tomorrow</literal> refer to
 142     00:00:00 of the current day, the day before or the next day,
 143     respectively.</para>
 144
 145     <para>When parsing, systemd will also accept relative time
 146     specifications. A time span (see above) that is prefixed with
 147     <literal>+</literal> is evaluated to the current time plus the
 148     specified time span. Correspondingly, a time span that is prefixed
 149     with <literal>-</literal> is evaluated to the current time minus
 150     the specified time span. Instead of prefixing the time span with
 151     <literal>+</literal> or <literal>-</literal>, it may also be
 152     suffixed with a space and the word <literal>left</literal> or
 153     <literal>ago</literal>.</para>
 154
 155     <para>Finally, a timespan prefixed with <literal>@</literal> is
 156     evaluated relative to the UNIX time epoch 1st Jan, 1970,
 157     00:00.</para>
 158
 159     <para>Examples for valid timestamps and their normalized form
 160     (assuming the current time was 2012-11-23 18:15:22):</para>
 161
 162     <programlisting>Fri 2012-11-23 11:12:13 → Fri 2012-11-23 11:12:13
 163     2012-11-23 11:12:13 → Fri 2012-11-23 11:12:13
 164        2012-11-23 → Fri 2012-11-23 00:00:00
 165          12-11-23 → Fri 2012-11-23 00:00:00
 166          11:12:13 → Fri 2012-11-23 11:12:13
 167       11:12 → Fri 2012-11-23 11:12:00
 168         now → Fri 2012-11-23 18:15:22
 169       today → Fri 2012-11-23 00:00:00
 170         yesterday → Fri 2012-11-22 00:00:00
 171          tomorrow → Fri 2012-11-24 00:00:00
 172          +3h30min → Fri 2012-11-23 21:45:22
 173         -5s → Fri 2012-11-23 18:15:17
 174         11min ago → Fri 2012-11-23 18:04:22
 175       @1395716396 → Tue 2014-03-25 03:59:56</programlisting>
 176
 177     <para>Note that timestamps printed by systemd will not be parsed
 178     correctly by systemd, as the timezone specification is not
 179     accepted, and printing timestamps is subject to locale settings
 180     for the weekday while parsing only accepts English weekday
 181     names.</para>
 182
 183     <para>In some cases, systemd will display a relative timestamp
 184     (relative to the current time, or the time of invocation of the
 185     command) instead or in addition to an absolute timestamp as
 186     described above. A relative timestamp is formatted as
 187     follows:</para>
 188
 189     <para>2 months 5 days ago</para>
 190
 191     <para>Note that any relative timestamp will also parse correctly
 192     where a timestamp is expected. (see above)</para>
 193   </refsect1>
 194
 195   <refsect1>
 196     <title>Calendar Events</title>
 197
 198     <para>Calendar events may be used to refer to one or more points
 199     in time in a single expression. They form a superset of the
 200     absolute timestamps explained above:</para>
 201
 202     <programlisting>Thu,Fri 2012-*-1,5 11:12:13</programlisting>
 203
 204     <para>The above refers to 11:12:13 of the first or fifth day of
 205     any month of the year 2012, but only if that day is a Thursday or
 206     Friday.</para>
 207
 208     <para>The weekday specification is optional. If specified, it
 209     should consist of one or more English language weekday names,
 210     either in the abbreviated (Wed) or non-abbreviated (Wednesday)
 211     form (case does not matter), separated by commas. Specifying two
 212     weekdays separated by <literal>-</literal> refers to a range of
 213     continuous weekdays. <literal>,</literal> and <literal>-</literal>
 214     may be combined freely.</para>
 215
 216     <para>In the date and time specifications, any component may be
 217     specified as <literal>*</literal> in which case any value will
 218     match. Alternatively, each component can be specified as a list of
 219     values separated by commas. Values may also be suffixed with
 220     <literal>/</literal> and a repetition value, which indicates that
 221     the value and all values plus multiples of the repetition value
 222     are matched.</para>
 223
 224     <para>Either time or date specification may be omitted, in which
 225     case the current day and 00:00:00 is implied, respectively. If the
 226     second component is not specified, <literal>:00</literal> is
 227     assumed.</para>
 228
 229     <para>Timezone names may not be specified.</para>
 230
 231     <para>The special expressions
 232     <literal>minutely</literal>,
 233     <literal>hourly</literal>, <literal>daily</literal>,
 234     <literal>monthly</literal>, <literal>weekly</literal>,
 235     <literal>yearly</literal>,
 236     <literal>quarterly</literal>,
 237     <literal>semiannually</literal> may be used as
 238     calendar events which refer to
 239     <literal>*-*-* *:*:00</literal>,
 240     <literal>*-*-* *:00:00</literal>,
 241     <literal>*-*-* 00:00:00</literal>,
 242     <literal>*-*-01 00:00:00</literal>,
 243     <literal>Mon *-*-* 00:00:00</literal>,
 244     <literal>*-01-01 00:00:00</literal>,
 245     <literal>*-01,04,07,10-01 00:00:0</literal> and
 246     <literal>*-01,07-01 00:00:00</literal> respectively.
 247     </para>
 248
 249     <para>Examples for valid timestamps and their
 250     normalized form:</para>
 251
 252 <programlisting>   Sat,Thu,Mon-Wed,Sat-Sun → Mon-Thu,Sat,Sun *-*-* 00:00:00
 253      Mon,Sun 12-*-* 2,1:23 → Mon,Sun 2012-*-* 01,02:23:00
 254        Wed *-1 → Wed *-*-01 00:00:00
 255      Wed-Wed,Wed *-1 → Wed *-*-01 00:00:00
 256     Wed, 17:48 → Wed *-*-* 17:48:00
 257 Wed-Sat,Tue 12-10-15 1:2:3 → Tue-Sat 2012-10-15 01:02:03
 258          *-*-7 0:0:0 → *-*-07 00:00:00
 259          10-15 → *-10-15 00:00:00
 260        monday *-12-* 17:00 → Mon *-12-* 17:00:00
 261  Mon,Fri *-*-3,1,2 *:30:45 → Mon,Fri *-*-01,02,03 *:30:45
 262       12,14,13,12:20,10,30 → *-*-* 12,13,14:10,20,30:00
 263  mon,fri *-1/2-1,3 *:30:45 → Mon,Fri *-01/2-01,03 *:30:45
 264       03-05 08:05:40 → *-03-05 08:05:40
 265       08:05:40 → *-*-* 08:05:40
 266          05:40 → *-*-* 05:40:00
 267     Sat,Sun 12-05 08:05:40 → Sat,Sun *-12-05 08:05:40
 268     Sat,Sun 08:05:40 → Sat,Sun *-*-* 08:05:40
 269     2003-03-05 05:40 → 2003-03-05 05:40:00
 270     2003-03-05 → 2003-03-05 00:00:00
 271          03-05 → *-03-05 00:00:00
 272         hourly → *-*-* *:00:00
 273          daily → *-*-* 00:00:00
 274        monthly → *-*-01 00:00:00
 275         weekly → Mon *-*-* 00:00:00
 276         yearly → *-01-01 00:00:00
 277       annually → *-01-01 00:00:00
 278          *:2/3 → *-*-* *:02/3:00</programlisting>
 279
 280       <para>Calendar events are used by timer units, see
 281       <citerefentry><refentrytitle>systemd.timer</refentrytitle><manvolnum>5</manvolnum></citerefentry>
 282       for details.</para>
 283
 284   </refsect1>
 285
 286   <refsect1>
 287       <title>See Also</title>
 288       <para>
 289         <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 290         <citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 291         <citerefentry><refentrytitle>systemd.timer</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 292         <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 293         <citerefentry><refentrytitle>systemd.directives</refentrytitle><manvolnum>7</manvolnum></citerefentry>
 294       </para>
 295   </refsect1>
 296
 297 </refentry>