| <?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, time spans, and calendar |
| events are displayed and may be specified in closely |
| related syntaxes.</para> |
| </refsect1> |
| |
| <refsect1> |
| <title>Displaying Time Spans</title> |
| |
| <para>Time spans refer to time durations. On display, |
| systemd will present time spans 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 Time Spans</title> |
| |
| <para>When parsing, systemd will accept the same |
| time span 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 time span allows for this.</para> |
| |
| <para>Examples for valid time span 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 weekday 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 weekday specification is optional, |
| but when the weekday is specified it must either be |
| in the abbreviated (<literal>Wed</literal>) or |
| non-abbreviated (<literal>Wednesday</literal>) English |
| language form (case does not 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 weekday |
| 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 time span (see above) that is |
| prefixed with <literal>+</literal> is evaluated to the |
| current time plus the specified time |
| span. Correspondingly, a time span that is prefixed |
| with <literal>-</literal> is evaluated to the current |
| time minus the specified time span. Instead of |
| prefixing the time span with <literal>+</literal> or |
| <literal>-</literal>, it may also be suffixed with a |
| space and the word <literal>left</literal> or |
| <literal>ago</literal>.</para> |
| |
| <para>Finally, a timespan prefixed with |
| <literal>@</literal> is evaluated relative to the UNIX |
| time epoch 1st Jan, 1970, 00:00.</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 |
| @1395716396 → Tue 2014-03-25 03:59:56</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 weekday while |
| parsing only accepts English weekday 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 weekday names, either in the abbreviated |
| (Wed) or non-abbreviated (Wednesday) form (case does |
| not matter), separated by commas. Specifying two |
| weekdays separated by <literal>-</literal> refers to a |
| range of continuous weekdays. <literal>,</literal> and |
| <literal>-</literal> may be combined freely.</para> |
| |
| <para>In the date and time specifications, any |
| component may be specified as <literal>*</literal> in |
| which case any value will match. Alternatively, each |
| component can be specified as a list of values separated |
| by commas. Values may also be suffixed with |
| <literal>/</literal> 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, <literal>:00</literal> is assumed.</para> |
| |
| <para>Timezone names may not be specified.</para> |
| |
| <para>The special expressions |
| <literal>minutely</literal>, |
| <literal>hourly</literal>, <literal>daily</literal>, |
| <literal>monthly</literal>, <literal>weekly</literal>, |
| <literal>yearly</literal>, |
| <literal>quarterly</literal>, |
| <literal>semiannually</literal> may be used as |
| calendar events which refer to |
| <literal>*-*-* *:*:00</literal>, |
| <literal>*-*-* *:00:00</literal>, |
| <literal>*-*-* 00:00:00</literal>, |
| <literal>*-*-01 00:00:00</literal>, |
| <literal>Mon *-*-* 00:00:00</literal>, |
| <literal>*-01-01 00:00:00</literal>, |
| <literal>*-01,04,07,10-01 00:00:0</literal> and |
| <literal>*-01,07-01 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 |
| yearly → *-01-01 00:00:00 |
| annually → *-01-01 00:00:00 |
| *:2/3 → *-*-* *:02/3:00</programlisting> |
| |
| <para>Calendar events are used by timer units, see |
| <citerefentry><refentrytitle>systemd.timer</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>, |
| <citerefentry><refentrytitle>systemd.directives</refentrytitle><manvolnum>7</manvolnum></citerefentry> |
| </para> |
| </refsect1> |
| |
| </refentry> |