s-s-d: Documentation improvements

Cosmetic fixes to start-stop-daemon output and man page. Document
that --chuid will change the group even if it has not been specified.
Add EXIT STATUS and EXAMPLE sections to man page.

ChangeLog

@@ -1,3 +1,13 @@
+2008-01-30  Justin Pryzby  <jpryzby+d@quoininc.com>
+
+	* utils/start-stop-daemon.c (do_help): Clarify --name and --user
+	options.
+	(parse_options): Reword --make-pidfile badusage.
+	(pid_is_cmd): Fix typo in comment.
+	* man/start-stop-daemon.8: Cosmetic fixes. Document that --chuid
+	will change the group even if it has not been specified. Add EXIT
+	STATUS and EXAMPLE sections.
+
 2008-01-29  Raphael Hertzog  <hertzog@debian.org>
 
 	* scripts/dpkg-buildpackage.pl: Add a new -R option to be able to replace

debian/changelog

@@ -8,6 +8,9 @@ dpkg (1.14.17) UNRELEASED; urgency=low
     Thanks to Colin Watson.
   * Use system timersub and fix timeval normalization in multiplication in
     start-stop-daemon. Thanks to Andreas Påhlsson. Closes: #462225
+  * Cosmetic fixes to start-stop-daemon output and man page. Document that
+    --chuid will change the group even if it has not been specified. Add
+    EXIT STATUS and EXAMPLE sections to man page. Thanks to Justin Pryzby.
 
   [ Raphael Hertzog ]
   * Add a warning displayed by dpkg-genchanges if the current version is

man/start-stop-daemon.8

@@ -1,4 +1,4 @@
-.TH start\-stop\-daemon 8 "2008-01-20" "Debian Project" "dpkg utilities"
+.TH start\-stop\-daemon 8 "2008-01-30" "Debian Project" "dpkg utilities"
 .SH NAME
 start\-stop\-daemon \- start and stop system daemon programs
 .
@@ -29,7 +29,7 @@ sent the KILL signal if
 .BR \-\-stop
 is specified. For daemons which have long-lived children
 which need to live through a
-.BR \-\-stop
+.BR \-\-stop ,
 you must specify a pidfile.
 .
 .SH COMMANDS
@@ -43,9 +43,9 @@ does nothing, and exits with error status 1 (0 if
 is specified).
 If such a process does not exist, it starts an
 instance, using either the executable specified by
-.BR \-\-exec ,
-(or, if specified, by
-.BR \-\-startas ).
+.B \-\-exec
+or, if specified, by
+.BR \-\-startas .
 Any arguments given after
 .BR \-\-
 on the command line are passed unmodified to the program being
@@ -65,7 +65,7 @@ exits with error status 1
 .BR \-\-oknodo
 is specified). If
 .B \-\-retry
-is specified then
+is specified, then
 .B start\-stop\-daemon
 will check that the process(es) have terminated.
 .TP
@@ -120,7 +120,7 @@ then take further action as determined by the schedule.
 If
 .I timeout
 is specified instead of
-.I schedule
+.IR schedule ,
 then the schedule
 .IB signal / timeout /KILL/ timeout
 is used, where
@@ -178,6 +178,7 @@ specify a group by appending a
 .BR : ,
 then the group or gid in the same way
 as you would for the `chown' command (\fIuser\fP\fB:\fP\fIgroup\fP).
+If a user is specified without a group, the primary GID for that user is used.
 When using this option
 you must realize that the primary and supplemental groups are set as well,
 even if the
@@ -231,7 +232,7 @@ and place the pid into it just before executing the process. Note, the
 file will not be removed when stopping the program.
 .B NOTE:
 This feature may not work in all cases. Most notably when the program
-being executed forks from its main process. Because of this it is usually
+being executed forks from its main process. Because of this, it is usually
 only useful when combined with the
 .B \-\-background
 option.
@@ -239,6 +240,44 @@ option.
 .BR \-v ", " \-\-verbose
 Print verbose informational messages.
 .
+.SH EXIT STATUS
+.B start\-stop\-daemon
+returns 0 if the requested action was performed, or if
+.B \-\-oknodo
+is specified and either
+.B \-\-start
+was specified and a matching process was already running, or
+.B \-\-stop
+was specified and there were no matching processes. If
+.B \-\-oknodo
+was not specified and nothing was done, 1 is returned. If
+.B --stop
+and
+.B --retry
+were specified, but the end of the schedule was reached and the processes were
+still running, the error value is 2. For all other errors, the status is 3.
+.
+.SH EXAMPLE
+Start the \fBfood\fP daemon, unless one is already running (a process named
+food, running as user food, with pid in food.pid):
+.IP
+.nf
+start-stop-daemon --start --oknodo --user food --name food --pidfile /var/run/food.pid --startas /usr/sbin/food --chuid food -- --daemon
+.fi
+.PP
+Send \fBSIGTERM\fP to \fBfood\fP and wait up to 5 seconds for it to stop:
+.IP
+.nf
+start-stop-daemon --stop --oknodo --user food --name food --pidfile /var/run/food.pid --retry 5
+.fi
+.PP
+Demonstration of a custom schedule for stopping \fBfood\fP:
+.IP
+.nf
+start-stop-daemon --stop --oknodo --user food --name food --pidfile /var/run/food.pid --retry=TERM/30/KILL/5
+.fi
+.PP
+.
 .SH AUTHORS
 Marek Michalkiewicz <marekm@i17linuxb.ists.pwr.wroc.pl> based on
 a previous version by Ian Jackson <ian@chiark.greenend.org.uk>.

utils/start-stop-daemon.c

@@ -305,8 +305,8 @@ do_help(void)
 "Matching options (at least one is required):\n"
 "  -p|--pidfile <pid-file>       pid file to check\n"
 "  -x|--exec <executable>        program to start/check if it is running\n"
-"  -n|--name <process-name>      stop processes with this name\n"
-"  -u|--user <username|uid>      stop processes owned by this user\n"
+"  -n|--name <process-name>      process name to check\n"
+"  -u|--user <username|uid>      process owner to check\n"
 "\n"
 "Options:\n"
 "  -g|--group <group|gid>        run process as this group\n"
@@ -655,7 +655,7 @@ parse_options(int argc, char * const *argv)
 		badusage("--start needs --exec or --startas");
 
 	if (mpidfile && pidfile == NULL)
-		badusage("--make-pidfile is only relevant with --pidfile");
+		badusage("--make-pidfile requires --pidfile");
 
 	if (background && !start)
 		badusage("--background is only relevant with --start");
@@ -923,7 +923,7 @@ pid_is_cmd(pid_t pid, const char *name)
 		start_argv_0_p = *pid_argv_p;
 	else {
 		/* Tests indicate that this never happens, since
-		 * kvm_getargv itselfe cuts of tailing stuff. This is
+		 * kvm_getargv itself cuts of tailing stuff. This is
 		 * not what the manpage says, however. */
 		strncpy(buf, *pid_argv_p, (end_argv_0_p - start_argv_0_p));
 		buf[(end_argv_0_p - start_argv_0_p) + 1] = '\0';