diff options
Diffstat (limited to 'man/systemd.time.xml')
| -rw-r--r-- | man/systemd.time.xml | 525 |
1 files changed, 256 insertions, 269 deletions
diff --git a/man/systemd.time.xml b/man/systemd.time.xml index 2e64089c29..da0729725d 100644 --- a/man/systemd.time.xml +++ b/man/systemd.time.xml @@ -1,6 +1,6 @@ <?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"> + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> <!-- This file is part of systemd. @@ -23,288 +23,275 @@ <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 + <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 + </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, but only if that - day 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> + 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, but only if that day 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 *-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 + *-*-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 + 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> + 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> |