update TODO

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

diff --git a/man/systemd.service.xml b/man/systemd.service.xml
index 115d1692ed4390653ac312a75f2a8a64cd19efe1..4c890dfb7bbff42672a66f4a00fbcf7f2baa2268 100644 (file)
--- a/man/systemd.service.xml
+++ b/man/systemd.service.xml
@@ -301,9 +301,7 @@
                                 as. This option is mandatory for
                                 services where
                                 <varname>Type=</varname> is set to
                                 as. This option is mandatory for
                                 services where
                                 <varname>Type=</varname> is set to

-                                <option>dbus</option>, but its use
-                                is otherwise recommended if the process
-                                takes a name on the D-Bus bus.</para>
+                                <option>dbus</option>.</para>

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


@@ -379,11 +377,10 @@
 
                                 <para>For each of the specified
                                 commands, the first argument must be
 
                                 <para>For each of the specified
                                 commands, the first argument must be

-                                an absolute and literal path to an
-                                executable. Optionally, if the
-                                absolute file name is prefixed with
-                                <literal>@</literal>, the second token
-                                will be passed as
+                                an absolute path to an executable.
+                                Optionally, if this file name is
+                                prefixed with <literal>@</literal>,
+                                the second token will be passed as

                                 <literal>argv[0]</literal> to the
                                 executed process, followed by the
                                 further arguments specified. If the
                                 <literal>argv[0]</literal> to the
                                 executed process, followed by the
                                 further arguments specified. If the


@@ -593,8 +590,9 @@
                                 (i.e. the "keep-alive ping"). If the time
                                 between two such calls is larger than
                                 the configured time, then the service
                                 (i.e. the "keep-alive ping"). If the time
                                 between two such calls is larger than
                                 the configured time, then the service

-                                is placed in a failed state. By
-                                setting <varname>Restart=</varname> to
+                                is placed in a failed state and it will
+                                be terminated with <varname>SIGABRT</varname>.
+                                By setting <varname>Restart=</varname> to

                                 <option>on-failure</option> or
                                 <option>always</option>, the service
                                 will be automatically restarted. The
                                 <option>on-failure</option> or
                                 <option>always</option>, the service
                                 will be automatically restarted. The


@@ -1119,6 +1117,35 @@
                                 command.</para></listitem>
                         </varlistentry>
 
                                 command.</para></listitem>
                         </varlistentry>
 

+                        <varlistentry>
+                                <term><varname>FileDescriptorStoreMax=</varname></term>
+                                <listitem><para>Configure how many
+                                file descriptors may be stored in the
+                                service manager for the service using
+                                <citerefentry><refentrytitle>sd_pid_notify_with_fds</refentrytitle><manvolnum>3</manvolnum></citerefentry>'s
+                                <literal>FDSTORE=1</literal>
+                                messages. This is useful for
+                                implementing service restart schemes
+                                where the state is serialized to
+                                <filename>/run</filename> and the file
+                                descriptors passed to the service
+                                manager, to allow restarts without
+                                losing state. Defaults to 0, i.e. no
+                                file descriptors may be stored in the
+                                service manager by default. All file
+                                descriptors passed to the service
+                                manager from a specific service are
+                                passed back to the service's main
+                                process on the next service
+                                restart. Any file descriptors passed
+                                to the service manager are
+                                automatically closed when POLLHUP or
+                                POLLERR is seen on them, or when the
+                                service is fully stopped and no job
+                                queued or being executed for
+                                it.</para></listitem>
+                        </varlistentry>
+

                 </variablelist>
 
                 <para>Check
                 </variablelist>
 
                 <para>Check


@@ -1129,40 +1156,6 @@
 
         </refsect1>
 
 
         </refsect1>
 

-        <refsect1>
-                <title>Compatibility Options</title>
-
-                <para>The following options are also available in the
-                <literal>[Service]</literal> section, but exist purely
-                for compatibility reasons and should not be used in
-                newly written service files.</para>
-
-                <variablelist class='unit-directives'>
-                        <varlistentry>
-                                <term><varname>SysVStartPriority=</varname></term>
-                                <listitem><para>Set the SysV start
-                                priority to use to order this service
-                                in relation to SysV services lacking
-                                LSB headers. This option is only
-                                necessary to fix ordering in relation
-                                to legacy SysV services that have no
-                                ordering information encoded in the
-                                script headers. As such, it should only
-                                be used as a temporary compatibility
-                                option and should not be used in new unit
-                                files. Almost always, it is a better
-                                choice to add explicit ordering
-                                directives via
-                                <varname>After=</varname> or
-                                <varname>Before=</varname>,
-                                instead. For more details, see
-                                <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
-                                If used, pass an integer value in the
-                                range 0-99.</para></listitem>
-                        </varlistentry>
-                </variablelist>
-        </refsect1>
-

         <refsect1>
                 <title>Command lines</title>
 
         <refsect1>
                 <title>Command lines</title>
 


@@ -1183,13 +1176,15 @@
 
                 <para>Each command line is split on whitespace, with
                 the first item being the command to execute, and the
 
                 <para>Each command line is split on whitespace, with
                 the first item being the command to execute, and the

-                subsequent items being the arguments.  Double quotes
+                subsequent items being the arguments. Double quotes

                 ("...") and single quotes ('...') may be used, in
                 which case everything until the next matching quote
                 ("...") and single quotes ('...') may be used, in
                 which case everything until the next matching quote

-                becomes part of the same argument. Quotes themselves
-                are removed after parsing. In addition, a trailing
-                backslash (<literal>\</literal>) may be used to merge
-                lines. </para>
+                becomes part of the same argument. C-style escapes are
+                also supported, see table below. Quotes themselves are
+                removed after parsing and escape sequences
+                substituted. In addition, a trailing backslash
+                (<literal>\</literal>) may be used to merge lines.
+                </para>

 
                 <para>This syntax is intended to be very similar to
                 shell syntax, but only the meta-characters and
 
                 <para>This syntax is intended to be very similar to
                 shell syntax, but only the meta-characters and


@@ -1203,6 +1198,10 @@
                 <emphasis>other elements of shell syntax are not
                 supported</emphasis>.</para>
 
                 <emphasis>other elements of shell syntax are not
                 supported</emphasis>.</para>
 

+                <para>The command to execute must an absolute path
+                name. It may contain spaces, but control characters
+                are not allowed.</para>
+

                 <para>The command line accepts <literal>%</literal>
                 specifiers as described in
                 <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
                 <para>The command line accepts <literal>%</literal>
                 specifiers as described in
                 <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>.


@@ -1288,6 +1287,74 @@ ExecStart=/bin/echo $ONE $TWO $THREE</programlisting>
                 <literal>&gt;/dev/null</literal>,
                 <literal>&amp;</literal>, <literal>;</literal>, and
                 <literal>/bin/ls</literal>.</para>
                 <literal>&gt;/dev/null</literal>,
                 <literal>&amp;</literal>, <literal>;</literal>, and
                 <literal>/bin/ls</literal>.</para>

+
+                <table>
+                        <title>C escapes supported in command lines and environment variables</title>
+                        <tgroup cols='2'>
+                                <colspec colname='escape' />
+                                <colspec colname='meaning' />
+                                <thead>
+                                        <row>
+                                                <entry>Literal</entry>
+                                                <entry>Actual value</entry>
+                                        </row>
+                                </thead>
+                                <tbody>
+                                        <row>
+                                                <entry><literal>\a</literal></entry>
+                                                <entry>bell</entry>
+                                        </row>
+                                        <row>
+                                                <entry><literal>\b</literal></entry>
+                                                <entry>backspace</entry>
+                                        </row>
+                                        <row>
+                                                <entry><literal>\f</literal></entry>
+                                                <entry>form feed</entry>
+                                        </row>
+                                        <row>
+                                                <entry><literal>\n</literal></entry>
+                                                <entry>newline</entry>
+                                        </row>
+                                        <row>
+                                                <entry><literal>\r</literal></entry>
+                                                <entry>carriage return</entry>
+                                        </row>
+                                        <row>
+                                                <entry><literal>\t</literal></entry>
+                                                <entry>tab</entry>
+                                        </row>
+                                        <row>
+                                                <entry><literal>\v</literal></entry>
+                                                <entry>vertical tab</entry>
+                                        </row>
+                                        <row>
+                                                <entry><literal>\\</literal></entry>
+                                                <entry>backslash</entry>
+                                        </row>
+                                        <row>
+                                                <entry><literal>\"</literal></entry>
+                                                <entry>double quotation mark</entry>
+                                        </row>
+                                        <row>
+                                                <entry><literal>\'</literal></entry>
+                                                <entry>single quotation mark</entry>
+                                        </row>
+                                        <row>
+                                                <entry><literal>\s</literal></entry>
+                                                <entry>space</entry>
+                                        </row>
+                                        <row>
+                                                <entry><literal>\x<replaceable>xx</replaceable></literal></entry>
+                                                <entry>character number <replaceable>xx</replaceable> in hexadecimal encoding</entry>
+                                        </row>
+                                        <row>
+                                                <entry><literal>\<replaceable>nnn</replaceable></literal></entry>
+                                                <entry>character number <replaceable>nnn</replaceable> in octal encoding</entry>
+                                        </row>
+                                </tbody>
+                        </tgroup>
+                </table>

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