X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?p=elogind.git;a=blobdiff_plain;f=man%2Fdaemon.xml;h=5d3a9903da310d007cfb82878f4adc06506c2699;hp=7790420c6eb7154cfa80625f24fdb9db43cb0e2b;hb=f49481d0ca170ea567b46fde6c1c089b1dbb49cb;hpb=409dee2e44e7dc73d6bf00d782938e4cb4105f5b

diff --git a/man/daemon.xml b/man/daemon.xml
index 7790420c6..5d3a9903d 100644
--- a/man/daemon.xml
+++ b/man/daemon.xml
@@ -74,8 +74,8 @@
 
                         <orderedlist>
                                 <listitem><para>Close all open file
-                                descriptors except STDIN, STDOUT,
-                                STDERR (i.e. the first three file
+                                descriptors except standard input, output,
+                                and error (i.e. the first three file
                                 descriptors 0, 1, 2). This ensures
                                 that no accidentally passed file
                                 descriptor stays around in the daemon
@@ -85,13 +85,14 @@
                                 with a fallback of iterating from file
                                 descriptor 3 to the value returned by
                                 <function>getrlimit()</function> for
-                                RLIMIT_NOFILE.</para></listitem>
+                                <constant>RLIMIT_NOFILE</constant>.
+                                </para></listitem>
 
                                 <listitem><para>Reset all signal
                                 handlers to their default. This is
                                 best done by iterating through the
                                 available signals up to the limit of
-                                _NSIG and resetting them to
+                                <constant>_NSIG</constant> and resetting them to
                                 <constant>SIG_DFL</constant>.</para></listitem>
 
                                 <listitem><para>Reset the signal mask
@@ -128,8 +129,8 @@
 
                                 <listitem><para>In the daemon process,
                                 connect <filename>/dev/null</filename>
-                                to STDIN, STDOUT,
-                                STDERR.</para></listitem>
+                                to standard input, output, and error.
+                                </para></listitem>
 
                                 <listitem><para>In the daemon process,
                                 reset the umask to 0, so that the file
@@ -149,7 +150,7 @@
                                 write the daemon PID (as returned by
                                 <function>getpid()</function>) to a
                                 PID file, for example
-                                <filename>/var/run/foobar.pid</filename>
+                                <filename>/run/foobar.pid</filename>
                                 (for a hypothetical daemon "foobar")
                                 to ensure that the daemon cannot be
                                 started more than once. This must be
@@ -158,9 +159,7 @@
                                 it is verified at the same time that
                                 the PID previously stored in the PID
                                 file no longer exists or belongs to a
-                                foreign process. Commonly, some kind of
-                                file locking is employed to implement
-                                this logic.</para></listitem>
+                                foreign process.</para></listitem>
 
                                 <listitem><para>In the daemon process,
                                 drop privileges, if possible and
@@ -223,15 +222,16 @@
                         service.</para>
 
                         <para>Note that new-style init systems
-                        guarantee execution of daemon processes in
-                        a clean process context: it is guaranteed that
+                        guarantee execution of daemon processes in a
+                        clean process context: it is guaranteed that
                         the environment block is sanitized, that the
                         signal handlers and mask is reset and that no
                         left-over file descriptors are passed. Daemons
-                        will be executed in their own session, and
-                        STDIN/STDOUT/STDERR connected to
+                        will be executed in their own session, with
+                        standard input/output/error connected to
                         <filename>/dev/null</filename> unless
-                        otherwise configured. The umask is reset.</para>
+                        otherwise configured. The umask is reset.
+                        </para>
 
                         <para>It is recommended for new-style daemons
                         to implement the following:</para>
@@ -251,7 +251,7 @@
                                 detect service errors and problems. It
                                 is recommended to follow the exit code
                                 scheme as defined in the <ulink
-                                url="http://refspecs.freestandards.org/LSB_3.1.1/LSB-Core-generic/LSB-Core-generic/iniscrptact.html">LSB
+                                url="http://refspecs.linuxbase.org/LSB_3.1.1/LSB-Core-generic/LSB-Core-generic/iniscrptact.html">LSB
                                 recommendations for SysV init
                                 scripts</ulink>.</para></listitem>
 
@@ -322,29 +322,21 @@
                                 interface.</para></listitem>
 
                                 <listitem><para>Instead of using the
-                                <function>syslog()</function> call to log directly to the
-                                system syslog service, a new-style daemon may
-                                choose to simply log to STDERR via
-                                <function>fprintf()</function>, which is then forwarded to
-                                syslog by the init system. If log
-                                priorities are necessary, these can be
-                                encoded by prefixing individual log
-                                lines with strings like "&lt;4&gt;"
-                                (for log priority 4 "WARNING" in the
-                                syslog priority scheme), following a
-                                similar style as the Linux kernel's
-                                <function>printk()</function> priority system. In fact,
-                                using this style of logging also
-                                enables the init system to optionally
-                                direct all application logging to the
-                                kernel log buffer (kmsg), as
-                                accessible via
-                                <citerefentry><refentrytitle>dmesg</refentrytitle><manvolnum>1</manvolnum></citerefentry>. This
-                                kind of logging may be enabled by
-                                setting
-                                <varname>StandardError=syslog</varname>
-                                in the service unit file. For details,
-                                see
+                                <function>syslog()</function> call to
+                                log directly to the system syslog
+                                service, a new-style daemon may choose
+                                to simply log to standard error via
+                                <function>fprintf()</function>, which
+                                is then forwarded to syslog by the
+                                init system. If log levels are
+                                necessary, these can be encoded by
+                                prefixing individual log lines with
+                                strings like <literal>&lt;4&gt;</literal> (for log
+                                level 4 "WARNING" in the syslog
+                                priority scheme), following a similar
+                                style as the Linux kernel's
+                                <function>printk()</function> level
+                                system. For details, see
                                 <citerefentry><refentrytitle>sd-daemon</refentrytitle><manvolnum>3</manvolnum></citerefentry>
                                 and
                                 <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para></listitem>
@@ -353,7 +345,7 @@
 
                         <para>These recommendations are similar but
                         not identical to the <ulink
-                        url="http://developer.apple.com/mac/library/documentation/MacOSX/Conceptual/BPSystemStartup/Articles/LaunchOnDemandDaemons.html#//apple_ref/doc/uid/TP40001762-104738">Apple
+                        url="https://developer.apple.com/library/mac/documentation/MacOSX/Conceptual/BPSystemStartup/Chapters/CreatingLaunchdJobs.html">Apple
                         MacOS X Daemon Requirements</ulink>.</para>
                 </refsect2>
 
@@ -394,7 +386,7 @@
                         exclusively on boot (and manually by the
                         administrator) via SysV init scripts, as
                         detailed in the <ulink
-                        url="http://refspecs.freestandards.org/LSB_3.1.1/LSB-Core-generic/LSB-Core-generic/iniscrptact.html">LSB
+                        url="http://refspecs.linuxbase.org/LSB_3.1.1/LSB-Core-generic/LSB-Core-generic/iniscrptact.html">LSB
                         Linux Standard Base Core
                         Specification</ulink>. This method of
                         activation is supported ubiquitously on Linux
@@ -408,7 +400,7 @@
                         description files.</para>
 
                         <para>In systemd, if the developer or
-                        administrator wants to make sure a service or
+                        administrator wants to make sure that a service or
                         other unit is activated automatically on boot,
                         it is recommended to place a symlink to the
                         unit file in the <filename>.wants/</filename>
@@ -619,7 +611,7 @@
                         on a network interface, because network
                         sockets shall be bound to the
                         address. However, an alternative to implement
-                        this is by utilizing the Linux IP_FREEBIND
+                        this is by utilizing the Linux <constant>IP_FREEBIND</constant>
                         socket option, as accessible via
                         <varname>FreeBind=yes</varname> in systemd
                         socket files (see
@@ -757,7 +749,7 @@
                         boot.</para>
 
                         <para>Packages using
-                        <citerefentry><refentrytitle>autoconf</refentrytitle><manvolnum>1</manvolnum></citerefentry>
+                        <citerefentry project='die-net'><refentrytitle>autoconf</refentrytitle><manvolnum>1</manvolnum></citerefentry>
                         are recommended to use a configure script
                         excerpt like the following to determine the
                         unit installation path during source
@@ -765,12 +757,19 @@
 
                         <programlisting>PKG_PROG_PKG_CONFIG
 AC_ARG_WITH([systemdsystemunitdir],
-        AS_HELP_STRING([--with-systemdsystemunitdir=DIR], [Directory for systemd service files]),
-        [], [with_systemdsystemunitdir=$($PKG_CONFIG --variable=systemdsystemunitdir systemd)])
-if test "x$with_systemdsystemunitdir" != xno; then
-        AC_SUBST([systemdsystemunitdir], [$with_systemdsystemunitdir])
-fi
-AM_CONDITIONAL(HAVE_SYSTEMD, [test -n "$with_systemdsystemunitdir" -a "x$with_systemdsystemunitdir" != xno ])</programlisting>
+     [AS_HELP_STRING([--with-systemdsystemunitdir=DIR], [Directory for systemd service files])],,
+     [with_systemdsystemunitdir=auto])
+AS_IF([test "x$with_systemdsystemunitdir" = "xyes" -o "x$with_systemdsystemunitdir" = "xauto"], [
+     def_systemdsystemunitdir=$($PKG_CONFIG --variable=systemdsystemunitdir systemd)
+
+     AS_IF([test "x$def_systemdsystemunitdir" = "x"],
+         [AS_IF([test "x$with_systemdsystemunitdir" = "xyes"],
+                [AC_MSG_ERROR([systemd support requested but pkg-config unable to query systemd package])])
+          with_systemdsystemunitdir=no],
+         [with_systemdsystemunitdir="$def_systemdsystemunitdir"])])
+AS_IF([test "x$with_systemdsystemunitdir" != "xno"],
+      [AC_SUBST([systemdsystemunitdir], [$with_systemdsystemunitdir])])
+AM_CONDITIONAL([HAVE_SYSTEMD], [test "x$with_systemdsystemunitdir" != "xno"])</programlisting>
 
                         <para>This snippet allows automatic
                         installation of the unit files on systemd
@@ -785,7 +784,7 @@ AM_CONDITIONAL(HAVE_SYSTEMD, [test -n "$with_systemdsystemunitdir" -a "x$with_sy
                         work, it is recommended to add the following
                         to the top-level <filename>Makefile.am</filename>
                         file in
-                        <citerefentry><refentrytitle>automake</refentrytitle><manvolnum>1</manvolnum></citerefentry>-based
+                        <citerefentry project='die-net'><refentrytitle>automake</refentrytitle><manvolnum>1</manvolnum></citerefentry>-based
                         projects:</para>
 
                         <programlisting>DISTCHECK_CONFIGURE_FLAGS = \
@@ -800,7 +799,7 @@ systemdsystemunit_DATA = \
 endif</programlisting>
 
                         <para>In the
-                        <citerefentry><refentrytitle>rpm</refentrytitle><manvolnum>8</manvolnum></citerefentry>
+                        <citerefentry project='die-net'><refentrytitle>rpm</refentrytitle><manvolnum>8</manvolnum></citerefentry>
                         <filename>.spec</filename> file, use snippets
                         like the following to enable/disable the
                         service during
@@ -934,6 +933,14 @@ fi</programlisting>
                 </orderedlist>
         </refsect1>
 
+        <refsect1>
+                <title>Placing Daemon Data</title>
+
+                <para>It is recommended to follow the general
+                guidelines for placing package files, as discussed in
+                <citerefentry><refentrytitle>file-hierarchy</refentrytitle><manvolnum>7</manvolnum></citerefentry>.</para>
+        </refsect1>
+
         <refsect1>
                 <title>See Also</title>
                 <para>
@@ -942,7 +949,8 @@ fi</programlisting>
                         <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>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>
+                        <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
+                        <citerefentry><refentrytitle>file-hierarchy</refentrytitle><manvolnum>7</manvolnum></citerefentry>
                 </para>
         </refsect1>