man: always supply quotes around literals

[elogind.git] / man / daemon.xml

diff --git a/man/daemon.xml b/man/daemon.xml
index 997ee5b2534d0e9663fa78b78cb3196cacbacaf3..de362c1b71466f754a5a4473079f6357bd617af7 100644 (file)
--- a/man/daemon.xml
+++ b/man/daemon.xml
@@ -8,16 +8,16 @@
   Copyright 2010 Lennart Poettering
 
   systemd is free software; you can redistribute it and/or modify it
   Copyright 2010 Lennart Poettering
 
   systemd is free software; you can redistribute it and/or modify it

-  under the terms of the GNU General Public License as published by
-  the Free Software Foundation; either version 2 of the License, or
+  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
   (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

-  General Public License for more details.
+  Lesser General Public License for more details.

 
 

-  You should have received a copy of the GNU General Public License
+  You should have received a copy of the GNU Lesser General Public License

   along with systemd; If not, see <http://www.gnu.org/licenses/>.
 -->
 
   along with systemd; If not, see <http://www.gnu.org/licenses/>.
 -->
 


@@ -44,7 +44,7 @@
 
         <refnamediv>
                 <refname>daemon</refname>
 
         <refnamediv>
                 <refname>daemon</refname>

-                <refpurpose>Writing and Packaging System Daemons</refpurpose>
+                <refpurpose>Writing and packaging system daemons</refpurpose>

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


@@ -122,7 +122,7 @@
                                 first child, so that only the second
                                 child (the actual daemon process)
                                 stays around. This ensures that the
                                 first child, so that only the second
                                 child (the actual daemon process)
                                 stays around. This ensures that the

-                                daemon process is reparented to
+                                daemon process is re-parented to

                                 init/PID 1, as all daemons should
                                 be.</para></listitem>
 
                                 init/PID 1, as all daemons should
                                 be.</para></listitem>
 


@@ -181,11 +181,11 @@
                                 <function>exit()</function> in the
                                 original process. The process that
                                 invoked the daemon must be able to
                                 <function>exit()</function> in the
                                 original process. The process that
                                 invoked the daemon must be able to

-                                rely that this
+                                rely on that this

                                 <function>exit()</function> happens
                                 after initialization is complete and
                                 all external communication channels
                                 <function>exit()</function> happens
                                 after initialization is complete and
                                 all external communication channels

-                                established and
+                                are established and

                                 accessible.</para></listitem>
                         </orderedlist>
 
                                 accessible.</para></listitem>
                         </orderedlist>
 


@@ -196,7 +196,7 @@
                         compatibility with SysV systems should
                         implement the scheme pointed out
                         above. However, it is recommended to make this
                         compatibility with SysV systems should
                         implement the scheme pointed out
                         above. However, it is recommended to make this

-                        behaviour optional and configurable via a
+                        behavior optional and configurable via a

                         command line argument, to ease debugging as
                         well as to simplify integration into systems
                         using systemd.</para>
                         command line argument, to ease debugging as
                         well as to simplify integration into systems
                         using systemd.</para>


@@ -271,7 +271,7 @@
                                 for details.</para></listitem>
 
                                 <listitem><para>As much as possible,
                                 for details.</para></listitem>
 
                                 <listitem><para>As much as possible,

-                                rely on the init systemd's
+                                rely on the init system's

                                 functionality to limit the access of
                                 the daemon to files, services and
                                 other resources. i.e. in the case of
                                 functionality to limit the access of
                                 the daemon to files, services and
                                 other resources. i.e. in the case of


@@ -345,7 +345,7 @@
                                 <varname>StandardError=syslog</varname>
                                 in the service unit file. For details
                                 see
                                 <varname>StandardError=syslog</varname>
                                 in the service unit file. For details
                                 see

-                                <citerefentry><refentrytitle>sd-daemon</refentrytitle><manvolnum>7</manvolnum></citerefentry>
+                                <citerefentry><refentrytitle>sd-daemon</refentrytitle><manvolnum>3</manvolnum></citerefentry>

                                 and
                                 <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para></listitem>
 
                                 and
                                 <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para></listitem>
 


@@ -462,13 +462,13 @@
 
                         <para>New-style daemons which support socket
                         activation must be able to receive their
 
                         <para>New-style daemons which support socket
                         activation must be able to receive their

-                        sockets from the init system, instead of of
+                        sockets from the init system, instead of

                         creating and binding them themselves. For
                         details about the programming interfaces for
                         this scheme provided by systemd see
                         <citerefentry><refentrytitle>sd_listen_fds</refentrytitle><manvolnum>3</manvolnum></citerefentry>
                         and
                         creating and binding them themselves. For
                         details about the programming interfaces for
                         this scheme provided by systemd see
                         <citerefentry><refentrytitle>sd_listen_fds</refentrytitle><manvolnum>3</manvolnum></citerefentry>
                         and

-                        <citerefentry><refentrytitle>sd-daemon</refentrytitle><manvolnum>7</manvolnum></citerefentry>. For
+                        <citerefentry><refentrytitle>sd-daemon</refentrytitle><manvolnum>3</manvolnum></citerefentry>. For

                         details about porting existing daemons to
                         socket-based activation see below. With
                         minimal effort it is possible to implement
                         details about porting existing daemons to
                         socket-based activation see below. With
                         minimal effort it is possible to implement


@@ -547,7 +547,7 @@
                         systemd, kernel devices appearing in the
                         sysfs/udev device tree can be exposed as units
                         if they are tagged with the string
                         systemd, kernel devices appearing in the
                         sysfs/udev device tree can be exposed as units
                         if they are tagged with the string

-                        "<literal>systemd</literal>". Like any other
+                        <literal>systemd</literal>. Like any other

                         kind of unit they may then pull in other units
                         when activated (i.e. Plugged in) and thus
                         implement device-based activation. Systemd
                         kind of unit they may then pull in other units
                         when activated (i.e. Plugged in) and thus
                         implement device-based activation. Systemd


@@ -740,7 +740,7 @@
                         directory returned by <command>pkg-config
                         systemd
                         --variable=systemdsystemunitdir</command> (for
                         directory returned by <command>pkg-config
                         systemd
                         --variable=systemdsystemunitdir</command> (for

-                        system services), resp. <command>pkg-config
+                        system services) or <command>pkg-config

                         systemd
                         --variable=systemduserunitdir</command>
                         (for user services). This will make the
                         systemd
                         --variable=systemduserunitdir</command>
                         (for user services). This will make the


@@ -801,48 +801,49 @@ endif</programlisting>
 
                         <para>In the
                         <citerefentry><refentrytitle>rpm</refentrytitle><manvolnum>8</manvolnum></citerefentry>
 
                         <para>In the
                         <citerefentry><refentrytitle>rpm</refentrytitle><manvolnum>8</manvolnum></citerefentry>

-                        <filename>.spec</filename> file use a snippet like
-                        the following to enable/disable the service
-                        during installation/deinstallation. Consult
+                        <filename>.spec</filename> file use snippets
+                        like the following to enable/disable the
+                        service during
+                        installation/deinstallation. This makes use of
+                        the RPM macros shipped along systemd. Consult

                         the packaging guidelines of your distribution
                         for details and the equivalent for other
                         the packaging guidelines of your distribution
                         for details and the equivalent for other

-                        package managers:</para>
+                        package managers.</para>
+
+                        <para>At the top of the file:</para>
+
+                        <programlisting>BuildRequires: systemd
+%{?systemd_requires}</programlisting>
+
+                        <para>And as scriptlets, further down:</para>

 
                         <programlisting>%post
 
                         <programlisting>%post

-if [ $1 -eq 1 ]; then
-        # On install (not upgrade), enable (but don't start) the
-        # units by default
-        /bin/systemctl enable foobar.service foobar.socket >/dev/null 2>&amp;1 || :
-
-        # Alternatively, just call
-        # /bin/systemctl daemon-reload >/dev/null 2>&amp;1 || :
-        # here, if the daemon should not be enabled by default on
-        # installation
-fi
+%systemd_post foobar.service foobar.socket

 
 %preun
 
 %preun

-if [ $1 -eq 0 ]; then
-        # On uninstall (not upgrade), disable and stop the units
-        /bin/systemctl --no-reload disable foobar.service foobar.socket >/dev/null 2>&amp;1 || :
-        /bin/systemctl stop foobar.service foobar.socket >/dev/null 2>&amp;1 || :
-fi
+%systemd_preun foobar.service foobar.socket

 
 %postun
 
 %postun

-# Reload init system configuration, to make systemd honour changed
-# or deleted unit files
-/bin/systemctl daemon-reload >/dev/null 2>&amp;1 || :
-if [ $1 -ge 1 ] ; then
-        # On upgrade (not uninstall), optionally, restart the daemon
-        /bin/systemctl try-restart foobar.service >/dev/null 2>&amp;1 || :
-fi</programlisting>
-
-                        <para>Depending on whether your service should
-                        or should not be started/stopped/restarted
-                        during package installation, deinstallation or
-                        upgrade, a different set of commands may be
-                        specified. See
-                        <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>
-                        for details.</para>
+%systemd_postun</programlisting>
+
+                        <para>If the service shall be restarted during
+                        upgrades replace the
+                        <literal>%postun</literal> scriptlet above
+                        with the following:</para>
+
+                        <programlisting>%postun
+%systemd_postun_with_restart foobar.service</programlisting>
+
+                        <para>Note that
+                        <literal>%systemd_post</literal> and
+                        <literal>%systemd_preun</literal> expect the
+                        names of all units that are installed/removed
+                        as arguments, separated by
+                        spaces. <literal>%systemd_postun</literal>
+                        expects no
+                        arguments. <literal>%systemd_postun_with_restart</literal>
+                        expects the units to restart as
+                        arguments.</para>

 
                         <para>To facilitate upgrades from a package
                         version that shipped only SysV init scripts to
 
                         <para>To facilitate upgrades from a package
                         version that shipped only SysV init scripts to


@@ -904,7 +905,7 @@ fi</programlisting>
                         <function>sd_listen_fds()</function> returns a
                         positive value), skip the socket creation step
                         and use the passed sockets. Secondly, ensure
                         <function>sd_listen_fds()</function> returns a
                         positive value), skip the socket creation step
                         and use the passed sockets. Secondly, ensure

-                        that the file-system socket nodes for local
+                        that the file system socket nodes for local

                         AF_UNIX sockets used in the socket-based
                         activation are not removed when the daemon
                         shuts down, if sockets have been
                         AF_UNIX sockets used in the socket-based
                         activation are not removed when the daemon
                         shuts down, if sockets have been


@@ -937,7 +938,7 @@ fi</programlisting>
                 <title>See Also</title>
                 <para>
                         <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
                 <title>See Also</title>
                 <para>
                         <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,

-                        <citerefentry><refentrytitle>sd-daemon</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
+                        <citerefentry><refentrytitle>sd-daemon</refentrytitle><manvolnum>3</manvolnum></citerefentry>,

                         <citerefentry><refentrytitle>sd_listen_fds</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
                         <citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
                         <citerefentry><refentrytitle>daemon</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
                         <citerefentry><refentrytitle>sd_listen_fds</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
                         <citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
                         <citerefentry><refentrytitle>daemon</refentrytitle><manvolnum>3</manvolnum></citerefentry>,