+<?xml version='1.0'?> <!--*-nxml-*-->
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+ "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
+
+<!--
+ This file is part of systemd.
+
+ Copyright 2010 Lennart Poettering
+
+ systemd is free software; you can redistribute it and/or modify it
+ under the terms of the GNU Lesser General Public License as published by
+ the Free Software Foundation; either version 2.1 of the License, or
+ (at your option) any later version.
+
+ systemd is distributed in the hope that it will be useful, but
+ WITHOUT ANY WARRANTY; without even the implied warranty of
+ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+ Lesser General Public License for more details.
+
+ You should have received a copy of the GNU Lesser General Public License
+ along with systemd; If not, see <http://www.gnu.org/licenses/>.
+-->
+
+<refentry id="systemd.time">
+
+ <refentryinfo>
+ <title>systemd.time</title>
+ <productname>systemd</productname>
+
+ <authorgroup>
+ <author>
+ <contrib>Developer</contrib>
+ <firstname>Lennart</firstname>
+ <surname>Poettering</surname>
+ <email>lennart@poettering.net</email>
+ </author>
+ </authorgroup>
+ </refentryinfo>
+
+ <refmeta>
+ <refentrytitle>systemd.time</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </refmeta>
+
+ <refnamediv>
+ <refname>systemd.time</refname>
+ <refpurpose>Time and date specifications</refpurpose>
+ </refnamediv>
+
+ <refsect1>
+ <title>Description</title>
+
+ <para>In systemd timestamps, timespans, and calendar
+ events are displayed and may be specified in closely
+ related syntaxes.</para>
+ </refsect1>
+
+ <refsect1>
+ <title>Displaying Timespans</title>
+
+ <para>Timespans refer to time durations. On display
+ systemd will present timespans as a space separated
+ series of time values each suffixed by a time
+ unit.</para>
+
+ <programlisting>2h 30min</programlisting>
+
+ <para>All specified time values are meant to be added
+ up. The above hence refers to 150 minutes.</para>
+ </refsect1>
+
+ <refsect1>
+ <title>Parsing Timespans</title>
+
+ <para>When parsing systemd will accept the same
+ timespan syntax. Separating spaces may be omitted. The
+ following time units are understood:</para>
+
+ <itemizedlist>
+ <listitem><para>usec, us</para></listitem>
+ <listitem><para>msec, ms</para></listitem>
+ <listitem><para>seconds, second, sec, s</para></listitem>
+ <listitem><para>minutes, minute, min, m</para></listitem>
+ <listitem><para>hours, hour, hr, h</para></listitem>
+ <listitem><para>days, day, d</para></listitem>
+ <listitem><para>weeks, week, w</para></listitem>
+ <listitem><para>months, month</para></listitem>
+ <listitem><para>years, year, y</para></listitem>
+ </itemizedlist>
+
+ <para>If no time unit is specified, generally seconds
+ are assumed, but some exceptions exist and are marked
+ as such. In a few cases <literal>ns</literal>,
+ <literal>nsec</literal> is accepted too, where the
+ granularity of the timespan allows for this.</para>
+
+ <para>Examples for valid timespan specifications:</para>
+
+ <programlisting>2 h
+2hours
+48hr
+1y 12month
+55s500ms
+300ms20s 5day</programlisting>
+ </refsect1>
+
+ <refsect1>
+ <title>Displaying Timestamps</title>
+
+ <para>Timestamps refer to specific, unique points in
+ time. On display systemd will format these in the
+ local timezone as follows:</para>
+
+ <programlisting>Fri 2012-11-23 23:02:15 CET</programlisting>
+
+ <para>The week day is printed according to the locale
+ choice of the user.</para>
+ </refsect1>
+
+ <refsect1>
+ <title>Parsing Timestamps</title>
+
+ <para>When parsing systemd will accept a similar
+ timestamp syntax, but excluding any timezone
+ specification (this limitation might be removed
+ eventually). The week day specification is optional,
+ but when the week day is specified it must either be
+ in the abbreviated (<literal>Wed</literal>) or
+ non-abbreviated (<literal>Wednesday</literal>) english
+ language form (case doesn't matter), and is not
+ subject to the locale choice of the user. Either the
+ date, or the time part may be omitted, in which case
+ the current date or 00:00:00, resp., is assumed. The
+ seconds component of the time may also be omitted, in
+ which case ":00" is assumed. Year numbers may be
+ specified in full or may be abbreviated (omitting the
+ century).</para>
+
+ <para>A timestamp is considered invalid if a week day
+ is specified and the date does not actually match the
+ specified day of the week.</para>
+
+ <para>When parsing systemd will also accept a few
+ special placeholders instead of timestamps:
+ <literal>now</literal> may be used to refer to the
+ current time (or of the invocation of the command
+ that is currently executed). <literal>today</literal>,
+ <literal>yesterday</literal>,
+ <literal>tomorrow</literal> refer to 00:00:00 of the
+ current day, the day before or the next day,
+ respectively.</para>
+
+ <para>When parsing systemd will also accept relative
+ time specifications. A timespan (see above) that is
+ prefixed with <literal>+</literal> is evaluated to the
+ current time plus the specified
+ timespan. Correspondingly a timespan that is prefix
+ with <literal>-</literal> is evaluated to the current
+ time minus the specified timespan. Instead of
+ prefixing the timespan with <literal>-</literal> it
+ may also be suffixed with a space and the word
+ <literal>ago</literal>.</para>
+
+ <para>Examples for valid timestamps and their
+ normalized form (assuming the current time was
+ 2012-11-23 18:15:22):</para>
+
+ <programlisting>Fri 2012-11-23 11:12:13 → Fri 2012-11-23 11:12:13
+ 2012-11-23 11:12:13 → Fri 2012-11-23 11:12:13
+ 2012-11-23 → Fri 2012-11-23 00:00:00
+ 12-11-23 → Fri 2012-11-23 00:00:00
+ 11:12:13 → Fri 2012-11-23 11:12:13
+ 11:12 → Fri 2012-11-23 11:12:00
+ now → Fri 2012-11-23 18:15:22
+ today → Fri 2012-11-23 00:00:00
+ yesterday → Fri 2012-11-22 00:00:00
+ tomorrow → Fri 2012-11-24 00:00:00
+ +3h30min → Fri 2012-11-23 21:45:22
+ -5s → Fri 2012-11-23 18:15:17
+ 11min ago → Fri 2012-11-23 18:04:22</programlisting>
+
+ <para>Note that timestamps printed by systemd will not
+ be parsed correctly by systemd, as the timezone
+ specification is not accepted, and printing timestamps
+ is subject to locale settings for the week day while
+ parsing only accepts english week day names.</para>
+
+ <para>In some cases systemd will display a relative
+ timestamp (relative to the current time, or the time
+ of invocation of the command) instead or in addition
+ to an absolute timestamp as described above. A
+ relative timestamp is formatted as follows:</para>
+
+ <para>2 months 5 days ago</para>
+
+ <para>Note that any relative timestamp will also parse
+ correctly where a timestamp is expected. (see above)</para>
+ </refsect1>
+
+ <refsect1>
+ <title>Calendar Events</title>
+
+ <para>Calendar events may be used to refer to one or
+ more points in time in a single expression. They form
+ a superset of the absolute timestamps explained above:</para>
+
+ <programlisting>Thu,Fri 2012-*-1,5 11:12:13</programlisting>
+
+ <para>The above refers to 11:12:13 of the first or
+ fifth day of any month of the year 2012, given that it
+ is a thursday or friday.</para>
+
+ <para>The weekday specification is optional. If
+ specified it should consist of one or more english
+ language week day names, either in the abbreviated
+ (Wed) or non-abbreviated (Wednesday) form (case does
+ not matter), separated by colons. Specifying two week
+ days separated by "-" refers to a range of continuous
+ week days. "," and "-" may be combined freely.</para>
+
+ <para>In the date and time specifications any
+ component may be specified as "*" in which case any
+ value will match. Alternatively, each component can be
+ specified as list of values separated by
+ colons. Values may also be suffixed with "/" and a
+ repetition value, which indicates that the value and
+ all values plus multiples of the repetition value are
+ matched.</para>
+
+ <para>Either time or date specification may be
+ omitted, in which case the current day and 00:00:00 is
+ implied, respectively. If the second component is not
+ specified ":00" is assumed.</para>
+
+ <para>Timezone names may not be specified.</para>
+
+ <para>The special expressions
+ <literal>hourly</literal>, <literal>daily</literal>,
+ <literal>monthly</literal> and <literal>weekly</literal>
+ may be used as calendar events which refer to
+ <literal>*-*-* *:00:00</literal>, <literal>*-*-*
+ 00:00:00</literal>, <literal>*-*-01 00:00:00</literal> and
+ <literal>Mon *-*-* 00:00:00</literal>,
+ respectively.</para>
+
+ <para>Examples for valid timestamps and their
+ normalized form:</para>
+
+<programlisting> Sat,Thu,Mon-Wed,Sat-Sun → Mon-Thu,Sat,Sun *-*-* 00:00:00
+ Mon,Sun 12-*-* 2,1:23 → Mon,Sun 2012-*-* 01,02:23:00
+ Wed *-1 → Wed *-*-01 00:00:00
+ Wed-Wed,Wed *-1 → Wed *-*-01 00:00:00
+ Wed, 17:48 → Wed *-*-* 17:48:00
+Wed-Sat,Tue 12-10-15 1:2:3 → Tue-Sat 2012-10-15 01:02:03
+ *-*-7 0:0:0 → *-*-07 00:00:00
+ 10-15 → *-10-15 00:00:00
+ monday *-12-* 17:00 → Mon *-12-* 17:00:00
+ Mon,Fri *-*-3,1,2 *:30:45 → Mon,Fri *-*-01,02,03 *:30:45
+ 12,14,13,12:20,10,30 → *-*-* 12,13,14:10,20,30:00
+ mon,fri *-1/2-1,3 *:30:45 → Mon,Fri *-01/2-01,03 *:30:45
+ 03-05 08:05:40 → *-03-05 08:05:40
+ 08:05:40 → *-*-* 08:05:40
+ 05:40 → *-*-* 05:40:00
+ Sat,Sun 12-05 08:05:40 → Sat,Sun *-12-05 08:05:40
+ Sat,Sun 08:05:40 → Sat,Sun *-*-* 08:05:40
+ 2003-03-05 05:40 → 2003-03-05 05:40:00
+ 2003-03-05 → 2003-03-05 00:00:00
+ 03-05 → *-03-05 00:00:00
+ hourly → *-*-* *:00:00
+ daily → *-*-* 00:00:00
+ monthly → *-*-01 00:00:00
+ weekly → Mon *-*-* 00:00:00
+ *:2/3 → *-*-* *:02/3:00</programlisting>
+
+ <para>Calendar events are used by timer units, see
+ <citerefentry><refentrytitle>systemd.time</refentrytitle><manvolnum>5</manvolnum></citerefentry>
+ for details.</para>
+
+ </refsect1>
+
+ <refsect1>
+ <title>See Also</title>
+ <para>
+ <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
+ <citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
+ <citerefentry><refentrytitle>systemd.timer</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
+ <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>
+ </para>
+ </refsect1>
+
+</refentry>
~ianmdlvl / elogind.git / commitdiff