time: add suppot for fractional time specifications

[elogind.git] / man / systemd.service.xml

diff --git a/man/systemd.service.xml b/man/systemd.service.xml
index 63e5b16e538c9bb6ad8b14066d63f62d255d08a2..b82a5c18173ea0b81ad297830c75871aef65b542 100644 (file)
--- a/man/systemd.service.xml
+++ b/man/systemd.service.xml
@@ -48,7 +48,7 @@
         </refnamediv>
 
         <refsynopsisdiv>
         </refnamediv>
 
         <refsynopsisdiv>

-                <para><filename>systemd.service</filename></para>
+                <para><filename><replaceable>service</replaceable>.service</filename></para>

         </refsynopsisdiv>
 
         <refsect1>
         </refsynopsisdiv>
 
         <refsect1>


@@ -121,7 +121,7 @@
                 options specific to the <literal>[Service]</literal>
                 section of service units are the following:</para>
 
                 options specific to the <literal>[Service]</literal>
                 section of service units are the following:</para>
 

-                <variablelist>
+                <variablelist class='unit-directives'>

                         <varlistentry>
                                 <term><varname>Type=</varname></term>
 
                         <varlistentry>
                                 <term><varname>Type=</varname></term>
 


@@ -298,10 +298,13 @@
                                 <term><varname>ExecStart=</varname></term>
                                 <listitem><para>Commands with their
                                 arguments that are executed when this
                                 <term><varname>ExecStart=</varname></term>
                                 <listitem><para>Commands with their
                                 arguments that are executed when this

-                                service is started.
-                                </para>
+                                service is started. The first
+                                argument must be an absolute path
+                                name.</para>

 
 

-                                <para>When
+                                <para>When <varname>Type</varname> is
+                                not <option>oneshot</option>, only one
+                                command may be given. When

                                 <varname>Type=oneshot</varname> is
                                 used, more than one command may be
                                 specified. Multiple command lines may
                                 <varname>Type=oneshot</varname> is
                                 used, more than one command may be
                                 specified. Multiple command lines may


@@ -315,14 +318,21 @@
                                 for compatibility with parsers
                                 suitable for XDG
                                 <filename>.desktop</filename> files.
                                 for compatibility with parsers
                                 suitable for XDG
                                 <filename>.desktop</filename> files.

-                                The commands are invoked one by
-                                one sequentially in the order they
-                                appear in the unit file.
-                                When <varname>Type</varname> is
-                                not <option>oneshot</option>, only one
-                                command may be given. Lone semicolons
-                                may be escaped as
-                                '<literal>\;</literal>'.</para>
+                                Lone semicolons may be escaped as
+                                '<literal>\;</literal>'. If the empty
+                                string is assigned to this option the
+                                list of commands to start is reset,
+                                prior assignments of this option will
+                                have no effect.</para>
+
+                                <para>If more than one command is
+                                specified, the commands are invoked
+                                one by one sequentially in the order
+                                they appear in the unit file. If one
+                                of the commands fails (and is not
+                                prefixed with '<literal>-</literal>'),
+                                other lines are not executed and the
+                                unit is considered failed.</para>

 
                                 <para>Unless
                                 <varname>Type=forking</varname> is
 
                                 <para>Unless
                                 <varname>Type=forking</varname> is


@@ -338,6 +348,26 @@
                                 line (i.e. the program to execute) may
                                 not include specifiers.</para>
 
                                 line (i.e. the program to execute) may
                                 not include specifiers.</para>
 

+                                <para>Basic environment variable
+                                substitution is supported. Use
+                                <literal>${FOO}</literal> as part of a
+                                word, or as a word of its own on the
+                                command line, in which case it will be
+                                replaced by the value of the
+                                environment variable including all
+                                whitespace it contains, resulting in a
+                                single argument.  Use
+                                <literal>$FOO</literal> as a separate
+                                word on the command line, in which
+                                case it will be replaced by the value
+                                of the environment variable split up
+                                at whitespace, resulting in zero or
+                                more arguments. Note that the first
+                                argument (i.e. the program to execute)
+                                may not be a variable, since it must
+                                be a literal and absolute path
+                                name.</para>
+

                                 <para>Optionally, if the absolute file
                                 name is prefixed with
                                 '<literal>@</literal>', the second token
                                 <para>Optionally, if the absolute file
                                 name is prefixed with
                                 '<literal>@</literal>', the second token


@@ -355,39 +385,19 @@
                                 '<literal>@</literal>' are used they
                                 can appear in either order.</para>
 
                                 '<literal>@</literal>' are used they
                                 can appear in either order.</para>
 

-                                <para>On top of that basic environment
-                                variable substitution is
-                                supported. Use
-                                <literal>${FOO}</literal> as part of a
-                                word, or as a word of its own on the
-                                command line, in which case it will be
-                                replaced by the value of the
-                                environment variable including all
-                                whitespace it contains, resulting in a
-                                single argument.  Use
-                                <literal>$FOO</literal> as a separate
-                                word on the command line, in which
-                                case it will be replaced by the value
-                                of the environment variable split up
-                                at whitespace, resulting in no or more
-                                arguments. Note that the first
-                                argument (i.e. the program to execute)
-                                may not be a variable, and must be a
-                                literal and absolute path
-                                name.</para>
-

                                 <para>Note that this setting does not
                                 directly support shell command
                                 lines. If shell command lines are to
                                 be used they need to be passed
                                 explicitly to a shell implementation
                                 <para>Note that this setting does not
                                 directly support shell command
                                 lines. If shell command lines are to
                                 be used they need to be passed
                                 explicitly to a shell implementation

-                                of some kind. Example:
-                                <literal>ExecStart=/bin/sh -c 'dmesg | tac'</literal></para>
+                                of some kind. Example:</para>
+                                <programlisting>ExecStart=/bin/sh -c 'dmesg | tac'
+                                </programlisting>

 
                                 <para>For services run by a user
                                 instance of systemd the special
                                 environment variable
 
                                 <para>For services run by a user
                                 instance of systemd the special
                                 environment variable

-                                <literal>MANAGERPID</literal> is set
+                                <varname>$MANAGERPID</varname> is set

                                 to the PID of the systemd
                                 instance.</para>
                                 </listitem>
                                 to the PID of the systemd
                                 instance.</para>
                                 </listitem>


@@ -405,6 +415,11 @@
                                 that multiple command lines are allowed
                                 and the commands are executed one
                                 after the other, serially.</para>
                                 that multiple command lines are allowed
                                 and the commands are executed one
                                 after the other, serially.</para>

+
+                                <para>If any of those commands (not
+                                prefixed with '<literal>-</literal>')
+                                fail, the rest are not executed and
+                                the unit is considered failed.</para>

                                 </listitem>
                         </varlistentry>
 
                                 </listitem>
                         </varlistentry>
 


@@ -420,14 +435,17 @@
                                 optional. Specifier and environment
                                 variable substitution is supported
                                 here following the same scheme as for
                                 optional. Specifier and environment
                                 variable substitution is supported
                                 here following the same scheme as for

-                                <varname>ExecStart=</varname>. One
-                                additional special environment
-                                variables is set: if known
-                                <literal>$MAINPID</literal> is set to
+                                <varname>ExecStart=</varname>.</para>
+
+                                <para>One additional special
+                                environment variables is set: if known
+                                <varname>$MAINPID</varname> is set to

                                 the main process of the daemon, and
                                 may be used for command lines like the
                                 the main process of the daemon, and
                                 may be used for command lines like the

-                                following: <command>/bin/kill -HUP
-                                $MAINPID</command>.</para></listitem>
+                                following:</para>
+
+                                <programlisting>/bin/kill -HUP $MAINPID</programlisting>
+                                </listitem>

                         </varlistentry>
 
                         <varlistentry>
                         </varlistentry>
 
                         <varlistentry>


@@ -451,7 +469,7 @@
                                 service stop is requested. Specifier
                                 and environment variable substitution
                                 is supported (including
                                 service stop is requested. Specifier
                                 and environment variable substitution
                                 is supported (including

-                                <literal>$MAINPID</literal>, see
+                                <varname>$MAINPID</varname>, see

                                 above).</para></listitem>
                         </varlistentry>
 
                                 above).</para></listitem>
                         </varlistentry>
 


@@ -459,9 +477,12 @@
                                 <term><varname>ExecStopPost=</varname></term>
                                 <listitem><para>Additional commands
                                 that are executed after the service
                                 <term><varname>ExecStopPost=</varname></term>
                                 <listitem><para>Additional commands
                                 that are executed after the service

-                                was stopped using the commands
-                                configured in
-                                <varname>ExecStop=</varname>. This
+                                was stopped. This includes cases where
+                                the commands configured in
+                                <varname>ExecStop=</varname> were used,
+                                where the service doesn't have any
+                                <varname>ExecStop=</varname> defined, or
+                                where the service exited unexpectedly. This

                                 argument takes multiple command lines,
                                 following the same scheme as described
                                 for <varname>ExecStart</varname>. Use
                                 argument takes multiple command lines,
                                 following the same scheme as described
                                 for <varname>ExecStart</varname>. Use


@@ -616,8 +637,14 @@
                                 SIGKILL</literal>", ensures that exit
                                 codes 1, 2, 8 and the termination
                                 signal SIGKILL are considered clean
                                 SIGKILL</literal>", ensures that exit
                                 codes 1, 2, 8 and the termination
                                 signal SIGKILL are considered clean

-                                service
-                                terminations.</para></listitem>
+                                service terminations. This option may
+                                appear more than once in which case
+                                the list of successful exit statuses
+                                is merged. If the empty string is
+                                assigned to this option the list is
+                                reset, all prior assignments of this
+                                option will have no
+                                effect.</para></listitem>

                         </varlistentry>
 
                         <varlistentry>
                         </varlistentry>
 
                         <varlistentry>


@@ -638,9 +665,16 @@
                                 logic. Example:
                                 "<literal>RestartPreventExitStatus=1 6
                                 SIGABRT</literal>", ensures that exit
                                 logic. Example:
                                 "<literal>RestartPreventExitStatus=1 6
                                 SIGABRT</literal>", ensures that exit

-                                codes 1 and 6 and the termination signal
-                                SIGABRT will not result in automatic
-                                service restarting.</para></listitem>
+                                codes 1 and 6 and the termination
+                                signal SIGABRT will not result in
+                                automatic service restarting. This
+                                option may appear more than once in
+                                which case the list of restart preventing
+                                statuses is merged. If the empty
+                                string is assigned to this option the
+                                list is reset, all prior assignments
+                                of this option will have no
+                                effect.</para></listitem>

                         </varlistentry>
 
                         <varlistentry>
                         </varlistentry>
 
                         <varlistentry>


@@ -728,7 +762,7 @@
                                 open access to the notification socket
                                 when using
                                 <varname>Type=notify</varname> or
                                 open access to the notification socket
                                 when using
                                 <varname>Type=notify</varname> or

-                                <varname>WatchdogUsec=</varname> (see
+                                <varname>WatchdogSec=</varname> (see

                                 above). If those options are used but
                                 <varname>NotifyAccess=</varname> not
                                 configured it will be implicitly set
                                 above). If those options are used but
                                 <varname>NotifyAccess=</varname> not
                                 configured it will be implicitly set


@@ -754,13 +788,22 @@
                                 same time. Also note that a different
                                 service may be activated on incoming
                                 traffic than inherits the sockets. Or
                                 same time. Also note that a different
                                 service may be activated on incoming
                                 traffic than inherits the sockets. Or

-                                in other words: The
+                                in other words: the

                                 <varname>Service=</varname> setting of
                                 <filename>.socket</filename> units
                                 <varname>Service=</varname> setting of
                                 <filename>.socket</filename> units

-                                doesn't have to match the inverse of the
-                                <varname>Sockets=</varname> setting of
-                                the <filename>.service</filename> it
-                                refers to.</para></listitem>
+                                doesn't have to match the inverse of
+                                the <varname>Sockets=</varname>
+                                setting of the
+                                <filename>.service</filename> it
+                                refers to.</para>
+
+                                <para>This option may appear more than
+                                once, in which case the list of socket
+                                units is merged. If the empty string
+                                is assigned to this option the list of
+                                sockets is reset, all prior uses of
+                                this setting will have no
+                                effect.</para></listitem>

                         </varlistentry>
 
                         <varlistentry>
                         </varlistentry>
 
                         <varlistentry>


@@ -861,7 +904,7 @@
                 for compatibility reasons and should not be used in
                 newly written service files.</para>
 
                 for compatibility reasons and should not be used in
                 newly written service files.</para>
 

-                <variablelist>
+                <variablelist class='unit-directives'>

                         <varlistentry>
                                 <term><varname>SysVStartPriority=</varname></term>
                                 <listitem><para>Set the SysV start
                         <varlistentry>
                                 <term><varname>SysVStartPriority=</varname></term>
                                 <listitem><para>Set the SysV start