[gentoo-doc-cvs] cvs commit: handbook-x86.xml hb-working-rcscripts.xml

[Josh Saddler]

nightmorph    06/09/07 08:23:02

  Modified:             handbook-x86.xml hb-working-rcscripts.xml
  Log:
  updated stop-start-daemon documentation for bug 122786

Revision  Changes    Path
1.153                xml/htdocs/doc/en/handbook/handbook-x86.xml

file : http://sources.gentoo.org/viewcvs.py/gentoo/xml/htdocs/doc/en/handbook/handbook-x86.xml?rev=1.153&view=markup
plain: http://sources.gentoo.org/viewcvs.py/gentoo/xml/htdocs/doc/en/handbook/handbook-x86.xml?rev=1.153&content-type=text/plain
diff : http://sources.gentoo.org/viewcvs.py/gentoo/xml/htdocs/doc/en/handbook/handbook-x86.xml?r1=1.152&r2=1.153

Index: handbook-x86.xml
===================================================================
RCS file: /var/cvsroot/gentoo/xml/htdocs/doc/en/handbook/handbook-x86.xml,v
retrieving revision 1.152
retrieving revision 1.153
diff -u -r1.152 -r1.153
--- handbook-x86.xml	30 Aug 2006 22:52:28 -0000	1.152
+++ handbook-x86.xml	7 Sep 2006 08:23:02 -0000	1.153
@@ -1,7 +1,7 @@
 <?xml version='1.0' encoding='UTF-8'?>
 <!DOCTYPE book SYSTEM "/dtd/book.dtd">
 
-<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/handbook/handbook-x86.xml,v 1.152 2006/08/30 22:52:28 nightmorph Exp $ -->
+<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/handbook/handbook-x86.xml,v 1.153 2006/09/07 08:23:02 nightmorph Exp $ -->
 
 <book link="/doc/en/handbook/handbook-x86.xml">
 <title>Gentoo Linux x86 Handbook</title>
@@ -111,6 +111,9 @@
 <author title="Editor">
   <mail link="neysx@g.o">Xavier Neys</mail>
 </author>
+<author title="Editor">
+  <mail link="nightmorph@g.o">Joshua Saddler</mail>
+</author>
 <author title="Reviewer">
     <mail link="g2boojum@g.o">Grant Goodyear</mail>
 </author>
@@ -137,8 +140,8 @@
 <!-- See http://creativecommons.org/licenses/by-sa/2.5 -->
 <license/>
 
-<version>7.0</version>
-<date>2006-08-30</date>
+<version>7.1</version>
+<date>2006-09-07</date>
 
 <part>
 <title>Installing Gentoo</title>



1.26                 xml/htdocs/doc/en/handbook/hb-working-rcscripts.xml

file : http://sources.gentoo.org/viewcvs.py/gentoo/xml/htdocs/doc/en/handbook/hb-working-rcscripts.xml?rev=1.26&view=markup
plain: http://sources.gentoo.org/viewcvs.py/gentoo/xml/htdocs/doc/en/handbook/hb-working-rcscripts.xml?rev=1.26&content-type=text/plain
diff : http://sources.gentoo.org/viewcvs.py/gentoo/xml/htdocs/doc/en/handbook/hb-working-rcscripts.xml?r1=1.25&r2=1.26

Index: hb-working-rcscripts.xml
===================================================================
RCS file: /var/cvsroot/gentoo/xml/htdocs/doc/en/handbook/hb-working-rcscripts.xml,v
retrieving revision 1.25
retrieving revision 1.26
diff -u -r1.25 -r1.26
--- hb-working-rcscripts.xml	14 Mar 2006 19:29:29 -0000	1.25
+++ hb-working-rcscripts.xml	7 Sep 2006 08:23:02 -0000	1.26
@@ -4,12 +4,12 @@
 <!-- The content of this document is licensed under the CC-BY-SA license -->
 <!-- See http://creativecommons.org/licenses/by-sa/2.5 -->
 
-<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/handbook/hb-working-rcscripts.xml,v 1.25 2006/03/14 19:29:29 neysx Exp $ -->
+<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/handbook/hb-working-rcscripts.xml,v 1.26 2006/09/07 08:23:02 nightmorph Exp $ -->
 
 <sections>
 
-<version>1.21</version>
-<date>2005-05-29</date>
+<version>1.22</version>
+<date>2006-09-07</date>
 
 <section>
 <title>Runlevels</title>
@@ -535,6 +535,19 @@
 }
 </pre>
 
+<p>
+If your service must write to local disks, it should need <c>localmount</c>. If
+it places anything in <path>/var/run</path> such as a pidfile, then should
+start after <c>bootmisc</c>:
+</p>
+
+<pre caption="Example depend() function">
+depend() {
+  need localmount
+  after bootmisc
+}
+</pre>
+
 </body>
 </subsection>
 <subsection>
@@ -551,21 +564,33 @@
 <pre caption="Example start() function">
 start() {
   ebegin "Starting my_service"
-  start-stop-daemon --start --quiet --exec /path/to/my_service
+  start-stop-daemon --start --exec /path/to/my_service \
+    --pidfile /path/to/my_pidfile
   eend $?
 }
 </pre>
 
 <p>
-If you need more examples of the <c>start()</c> function, please read the source
-code of the available init scripts in your <path>/etc/init.d</path> directory.
-As for <c>start-stop-daemon</c>, there is an excellent man page available if you
-need more information:
+Both <c>--exec</c> and <c>--pidfile</c> should be used in start and stop
+functions. If the service does not create a pidfile, then use
+<c>--make-pidfile</c> if possible, though you should test this to be sure.
+Otherwise, don't use pidfiles. You can also add <c>--quiet</c> to the
+<c>start-stop-daemon</c> options, but this is not recommended unless the
+service is extremely verbose.  Using <c>--quiet</c> may hinder debugging if the
+service fails to start.
 </p>
 
-<pre caption="Getting the man page for start-stop-daemon">
-# <i>man start-stop-daemon</i>
-</pre>
+<note>
+Make sure that <c>--exec</c> actually calls a service and not just a shell
+script that launches services and exits -- that's what the init script is
+supposed to do.
+</note>
+
+<p>
+If you need more examples of the <c>start()</c> function, please read the
+source code of the available init scripts in your <path>/etc/init.d</path>
+directory.
+</p>
 
 <p>
 Other functions you can define are: <c>stop()</c> and <c>restart()</c>. You are
@@ -574,6 +599,46 @@
 </p>
 
 <p>
+Although you do not <e>have</e> to create a <c>stop()</c> function, here is an
+example:
+</p>
+
+<pre caption="Example stop() function">
+stop() {
+  ebegin "Stopping my_service"
+  start-stop-daemon --stop --exec /path/to/my_service \
+    --pidfile /path/to/my_pidfile
+  eend $?
+}
+</pre>
+
+<p>
+If your service runs some other script (for example, bash, python, or perl),
+and this script later changes names (for example, <c>foo.py</c> to <c>foo</c>),
+then you will need to add <c>--name</c> to <c>start-stop-daemon</c>. You must
+specify the name that your script will be changed to. In this example, a
+service starts <c>foo.py</c>, which changes names to <c>foo</c>:
+</p>
+
+<pre caption="A service that starts the foo script">
+start() {
+  ebegin "Starting my_script"
+  start-stop-daemon --start --exec /path/to/my_script \
+    --pidfile /path/to/my_pidfile --name foo
+  eend $?
+}
+</pre>
+
+<p>
+<c>start-stop-daemon</c> has an excellent man page available if you need more
+information:
+</p>
+
+<pre caption="Getting the man page for start-stop-daemon">
+$ <i>man start-stop-daemon</i>
+</pre>
+
+<p>
 Gentoo's init script syntax is based on the Bourne Again Shell (bash) so you are
 free to use bash-compatible constructs inside your init script.
 </p>



-- 
gentoo-doc-cvs@g.o mailing list