From: Justin Pryzby Date: Wed, 30 Jan 2008 04:35:30 +0000 (+0200) Subject: s-s-d: Documentation improvements X-Git-Url: https://err.no/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=1f6feb233d4e7088cb920f386292f8d31d694d3a;p=dpkg 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. --- diff --git a/ChangeLog b/ChangeLog index 9ee2a7d1..1bbc5f79 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,13 @@ +2008-01-30 Justin Pryzby + + * 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 * scripts/dpkg-buildpackage.pl: Add a new -R option to be able to replace diff --git a/debian/changelog b/debian/changelog index 9e8b77e4..b3200736 100644 --- a/debian/changelog +++ b/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 diff --git a/man/start-stop-daemon.8 b/man/start-stop-daemon.8 index 5e12d1ef..4ed8a745 100644 --- a/man/start-stop-daemon.8 +++ b/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 based on a previous version by Ian Jackson . diff --git a/utils/start-stop-daemon.c b/utils/start-stop-daemon.c index 1494e55e..61081631 100644 --- a/utils/start-stop-daemon.c +++ b/utils/start-stop-daemon.c @@ -305,8 +305,8 @@ do_help(void) "Matching options (at least one is required):\n" " -p|--pidfile pid file to check\n" " -x|--exec program to start/check if it is running\n" -" -n|--name stop processes with this name\n" -" -u|--user stop processes owned by this user\n" +" -n|--name process name to check\n" +" -u|--user process owner to check\n" "\n" "Options:\n" " -g|--group 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';