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 <!ENTITY % entities SYSTEM "custom-entities.ent" >
   5 %entities;
   6 ]>
   7
   8 <!--
   9   This file is part of systemd.
  10
  11   Copyright 2010 Lennart Poettering
  12
  13   systemd is free software; you can redistribute it and/or modify it
  14   under the terms of the GNU Lesser General Public License as published by
  15   the Free Software Foundation; either version 2.1 of the License, or
  16   (at your option) any later version.
  17
  18   systemd is distributed in the hope that it will be useful, but
  19   WITHOUT ANY WARRANTY; without even the implied warranty of
  20   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
  21   Lesser General Public License for more details.
  22
  23   You should have received a copy of the GNU Lesser General Public License
  24   along with systemd; If not, see <http://www.gnu.org/licenses/>.
  25 -->
  26
  27 <refentry id="systemd.time">
  28
  29   <refentryinfo>
  30     <title>systemd.time</title>
  31     <productname>systemd</productname>
  32
  33     <authorgroup>
  34       <author>
  35         <contrib>Developer</contrib>
  36         <firstname>Lennart</firstname>
  37         <surname>Poettering</surname>
  38         <email>lennart@poettering.net</email>
  39       </author>
  40     </authorgroup>
  41   </refentryinfo>
  42
  43   <refmeta>
  44     <refentrytitle>systemd.time</refentrytitle>
  45     <manvolnum>7</manvolnum>
  46   </refmeta>
  47
  48   <refnamediv>
  49     <refname>systemd.time</refname>
  50     <refpurpose>Time and date specifications</refpurpose>
  51   </refnamediv>
  52
  53   <refsect1>
  54     <title>Description</title>
  55
  56     <para>In systemd, timestamps, time spans, and calendar events are
  57     displayed and may be specified in closely related syntaxes.</para>
  58   </refsect1>
  59
  60   <refsect1>
  61     <title>Displaying Time Spans</title>
  62
  63     <para>Time spans refer to time durations. On display, systemd will
  64     present time spans as a space-separated series of time values each
  65     suffixed by a time unit.</para>
  66
  67     <programlisting>2h 30min</programlisting>
  68
  69     <para>All specified time values are meant to be added up. The
  70     above hence refers to 150 minutes.</para>
  71   </refsect1>
  72
  73   <refsect1>
  74     <title>Parsing Time Spans</title>
  75
  76     <para>When parsing, systemd will accept the same time span syntax.
  77     Separating spaces may be omitted. The following time units are
  78     understood:</para>
  79
  80     <itemizedlist>
  81       <listitem><para>usec, us</para></listitem>
  82       <listitem><para>msec, ms</para></listitem>
  83       <listitem><para>seconds, second, sec, s</para></listitem>
  84       <listitem><para>minutes, minute, min, m</para></listitem>
  85       <listitem><para>hours, hour, hr, h</para></listitem>
  86       <listitem><para>days, day, d</para></listitem>
  87       <listitem><para>weeks, week, w</para></listitem>
  88       <listitem><para>months, month</para></listitem>
  89       <listitem><para>years, year, y</para></listitem>
  90     </itemizedlist>
  91
  92     <para>If no time unit is specified, generally seconds are assumed,
  93     but some exceptions exist and are marked as such. In a few cases
  94     <literal>ns</literal>, <literal>nsec</literal> is accepted too,
  95     where the 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 time. On
 111     display, systemd will format these in the local timezone as
 112     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 choice of the
 117     user.</para>
 118   </refsect1>
 119
 120   <refsect1>
 121     <title>Parsing Timestamps</title>
 122
 123     <para>When parsing systemd will accept a similar timestamp syntax,
 124     but excluding any timezone specification (this limitation might be
 125     removed eventually). The weekday specification is optional, but
 126     when the weekday is specified it must either be in the abbreviated
 127     (<literal>Wed</literal>) or non-abbreviated
 128     (<literal>Wednesday</literal>) English language form (case does
 129     not matter), and is not subject to the locale choice of the user.
 130     Either the date, or the time part may be omitted, in which case
 131     the current date or 00:00:00, resp., is assumed. The seconds
 132     component of the time may also be omitted, in which case ":00" is
 133     assumed. Year numbers may be specified in full or may be
 134     abbreviated (omitting the century).</para>
 135
 136     <para>A timestamp is considered invalid if a weekday is specified
 137     and the date does not actually match the specified day of the
 138     week.</para>
 139
 140     <para>When parsing, systemd will also accept a few special
 141     placeholders instead of timestamps: <literal>now</literal> may be
 142     used to refer to the current time (or of the invocation of the
 143     command that is currently executed). <literal>today</literal>,
 144     <literal>yesterday</literal>, <literal>tomorrow</literal> refer to
 145     00:00:00 of the current day, the day before or the next day,
 146     respectively.</para>
 147
 148     <para>When parsing, systemd will also accept relative time
 149     specifications. A time span (see above) that is prefixed with
 150     <literal>+</literal> is evaluated to the current time plus the
 151     specified time span. Correspondingly, a time span that is prefixed
 152     with <literal>-</literal> is evaluated to the current time minus
 153     the specified time span. Instead of prefixing the time span with
 154     <literal>+</literal> or <literal>-</literal>, it may also be
 155     suffixed with a space and the word <literal>left</literal> or
 156     <literal>ago</literal>.</para>
 157
 158     <para>Finally, a timespan prefixed with <literal>@</literal> is
 159     evaluated relative to the UNIX time epoch 1st Jan, 1970,
 160     00:00.</para>
 161
 162     <para>Examples for valid timestamps and their normalized form
 163     (assuming the current time was 2012-11-23 18:15:22):</para>
 164
 165     <programlisting>Fri 2012-11-23 11:12:13 → Fri 2012-11-23 11:12:13
 166     2012-11-23 11:12:13 → Fri 2012-11-23 11: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 → Fri 2012-11-23 11:12:00
 171         now → Fri 2012-11-23 18:15:22
 172       today → Fri 2012-11-23 00:00:00
 173         yesterday → Fri 2012-11-22 00:00:00
 174          tomorrow → Fri 2012-11-24 00:00:00
 175          +3h30min → Fri 2012-11-23 21:45:22
 176         -5s → Fri 2012-11-23 18:15:17
 177         11min ago → Fri 2012-11-23 18:04:22
 178       @1395716396 → Tue 2014-03-25 03:59:56</programlisting>
 179
 180     <para>Note that timestamps printed by systemd will not be parsed
 181     correctly by systemd, as the timezone specification is not
 182     accepted, and printing timestamps is subject to locale settings
 183     for the weekday while parsing only accepts English weekday
 184     names.</para>
 185
 186     <para>In some cases, systemd will display a relative timestamp
 187     (relative to the current time, or the time of invocation of the
 188     command) instead or in addition to an absolute timestamp as
 189     described above. A relative timestamp is formatted as
 190     follows:</para>
 191
 192     <para>2 months 5 days ago</para>
 193
 194     <para>Note that any relative timestamp will also parse correctly
 195     where a timestamp is expected. (see above)</para>
 196   </refsect1>
 197
 198   <refsect1>
 199     <title>Calendar Events</title>
 200
 201     <para>Calendar events may be used to refer to one or more points
 202     in time in a single expression. They form a superset of the
 203     absolute timestamps explained above:</para>
 204
 205     <programlisting>Thu,Fri 2012-*-1,5 11:12:13</programlisting>
 206
 207     <para>The above refers to 11:12:13 of the first or fifth day of
 208     any month of the year 2012, but only if that day is a Thursday or
 209     Friday.</para>
 210
 211     <para>The weekday specification is optional. If specified, it
 212     should consist of one or more English language weekday names,
 213     either in the abbreviated (Wed) or non-abbreviated (Wednesday)
 214     form (case does not matter), separated by commas. Specifying two
 215     weekdays separated by <literal>-</literal> refers to a range of
 216     continuous weekdays. <literal>,</literal> and <literal>-</literal>
 217     may be combined freely.</para>
 218
 219     <para>In the date and time specifications, any component may be
 220     specified as <literal>*</literal> in which case any value will
 221     match. Alternatively, each component can be specified as a list of
 222     values separated by commas. Values may also be suffixed with
 223     <literal>/</literal> and a repetition value, which indicates that
 224     the value and all values plus multiples of the repetition value
 225     are matched.</para>
 226
 227     <para>Either time or date specification may be omitted, in which
 228     case the current day and 00:00:00 is implied, respectively. If the
 229     second component is not specified, <literal>:00</literal> is
 230     assumed.</para>
 231
 232     <para>Timezone names may not be specified.</para>
 233
 234     <para>The special expressions
 235     <literal>minutely</literal>,
 236     <literal>hourly</literal>, <literal>daily</literal>,
 237     <literal>monthly</literal>, <literal>weekly</literal>,
 238     <literal>yearly</literal>,
 239     <literal>quarterly</literal>,
 240     <literal>semiannually</literal> may be used as
 241     calendar events which refer to
 242     <literal>*-*-* *:*:00</literal>,
 243     <literal>*-*-* *:00:00</literal>,
 244     <literal>*-*-* 00:00:00</literal>,
 245     <literal>*-*-01 00:00:00</literal>,
 246     <literal>Mon *-*-* 00:00:00</literal>,
 247     <literal>*-01-01 00:00:00</literal>,
 248     <literal>*-01,04,07,10-01 00:00:0</literal> and
 249     <literal>*-01,07-01 00:00:00</literal> respectively.
 250     </para>
 251
 252     <para>Examples for valid timestamps and their
 253     normalized form:</para>
 254
 255 <programlisting>   Sat,Thu,Mon-Wed,Sat-Sun → Mon-Thu,Sat,Sun *-*-* 00:00:00
 256      Mon,Sun 12-*-* 2,1:23 → Mon,Sun 2012-*-* 01,02:23:00
 257        Wed *-1 → Wed *-*-01 00:00:00
 258      Wed-Wed,Wed *-1 → Wed *-*-01 00:00:00
 259     Wed, 17:48 → Wed *-*-* 17:48:00
 260 Wed-Sat,Tue 12-10-15 1:2:3 → Tue-Sat 2012-10-15 01:02:03
 261          *-*-7 0:0:0 → *-*-07 00:00:00
 262          10-15 → *-10-15 00:00:00
 263        monday *-12-* 17:00 → Mon *-12-* 17:00:00
 264  Mon,Fri *-*-3,1,2 *:30:45 → Mon,Fri *-*-01,02,03 *:30:45
 265       12,14,13,12:20,10,30 → *-*-* 12,13,14:10,20,30:00
 266  mon,fri *-1/2-1,3 *:30:45 → Mon,Fri *-01/2-01,03 *:30:45
 267       03-05 08:05:40 → *-03-05 08:05:40
 268       08:05:40 → *-*-* 08:05:40
 269          05:40 → *-*-* 05:40:00
 270     Sat,Sun 12-05 08:05:40 → Sat,Sun *-12-05 08:05:40
 271     Sat,Sun 08:05:40 → Sat,Sun *-*-* 08:05:40
 272     2003-03-05 05:40 → 2003-03-05 05:40:00
 273     2003-03-05 → 2003-03-05 00:00:00
 274          03-05 → *-03-05 00:00:00
 275         hourly → *-*-* *:00:00
 276          daily → *-*-* 00:00:00
 277        monthly → *-*-01 00:00:00
 278         weekly → Mon *-*-* 00:00:00
 279         yearly → *-01-01 00:00:00
 280       annually → *-01-01 00:00:00
 281          *:2/3 → *-*-* *:02/3:00</programlisting>
 282
 283       <para>Calendar events are used by timer units, see
 284       <citerefentry><refentrytitle>systemd.timer</refentrytitle><manvolnum>5</manvolnum></citerefentry>
 285       for details.</para>
 286
 287   </refsect1>
 288
 289   <refsect1>
 290       <title>See Also</title>
 291       <para>
 292         <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 293         <citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 294         <citerefentry><refentrytitle>systemd.timer</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 295         <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 296         <citerefentry><refentrytitle>systemd.directives</refentrytitle><manvolnum>7</manvolnum></citerefentry>
 297       </para>
 298   </refsect1>
 299
 300 </refentry>