Rework the manpages into mdoc format for easier maintainence

1 files changed, 132 insertions, 235 deletions

diff --git a/man/start-stop-daemon.8 b/man/start-stop-daemon.8
index d674a0ba..59440680 100644
--- a/man/start-stop-daemon.8
+++ b/man/start-stop-daemon.8
@@ -1,237 +1,134 @@
-.TH "OPENRC" "13" "Nov 2007" "openrc" "openrc"
-.SH NAME
-start\-stop\-daemon \- start and stop system daemon programs
-.SH SYNOPSIS
-.B start-stop-daemon
-.BR -S | --start
-.IR options
-.RB [ \-\- ]
-.IR arguments
-.HP
-.B start-stop-daemon
-.BR -K | --stop
-.IR options
-.HP
-.B start-stop-daemon
-.BR -s | --signal
-.IR options
-.HP
-.B start-stop-daemon
-.BR -H | --help
-.HP
-.B start-stop-daemon
-.BR -V | --version
-.SH DESCRIPTION
-.B start\-stop\-daemon
-is used to control the creation and termination of system-level processes.
-Using the
-.BR --exec ", " --pidfile ", " --user ", and " --name " options,"
-.B start\-stop\-daemon
-can be configured to find existing instances of a running process.
-
-With
-.BR --start ,
-.B start\-stop\-daemon
-checks for the existence of a specified process.
-If such a process exists,
-.B start\-stop\-daemon
-does nothing, and exits with error status 1.
-If such a process does not exist, it starts an
-instance, using the executable specified by
-.BR --exec . 
-Any arguments given after
-.BR --
-on the command line are passed unmodified to the program being
-started.
-.B start\-stop\-daemon
-pauses for a little bit then checks the daemon is still running as badly
-written ones like to fork early and then bail on a error in their config.
-As such it may be necessary to use the --name parameter if the daemon in
-question is not a C program, ie a script. Once started, we store how we
-are called in \fBrc\fR if called from an init script.
-
-With 
-.BR --stop ,
-.B start\-stop\-daemon
-also checks for the existence of a specified process.
-If such a process exists,
-.B start\-stop\-daemon
-sends it the signal specified by
-.BR --signal ,
-and exits with error status 0.
-If such a process does not exist, or there was an error stopping it
-.B start\-stop\-daemon
-exits with error status 1. If
-.BR --test
-is specified then we just send the signal and not the schedule. If
-.BR --oknodo
-is specified then we don't remove the daemon information from
-.BR rc. If neither
-.BR --test
-or
-.BR --okndo
-are specified then we kill signalling and waiting according to our
-schedule specified by
-.BR --retry
-until we timeout the process(es) exited. If we didn't timeout then
-we remove our daemon information from rc.
-
-With 
-.BR --signal ,
-.B start\-stop\-daemon
-also checks for the existence of a specified process.
-If such a process exists,
-.B start\-stop\-daemon
-sends it the signal specified and exits with error status 0.
-If such a process does not exist, or there was an error stopping it
-.B start\-stop\-daemon
-exits with error status 1. No futher action is taken
-
-.SH OPTIONS
-
-.TP
-\fB-x\fP|\fB--exec\fP \fIexecutable\fP
-Check for processes that are instances of this executable.
-.TP
-\fB-p\fP|\fB--pidfile\fP \fIpid-file\fP
-Check for processes whose process-id is specified in 
-.I pid-file.
-.TP
-\fB-u\fP|\fB--user\fP \fIusername\fP|\fIuid\fP
-Check for processes owned by the user specified by
-.I username 
-or
-.I uid.
-.TP
-\fB-n\fP|\fB--name\fP \fIprocess-name\fP
-Check for processes with the name
-.I process-name
-.TP
-\fB-s\fP|\fB--signal\fP \fIsignal\fP
-With
-.BR --stop
-, specifies the signal to send to processes being stopped (default SIGTERM).
-.TP
-\fB-R\fP|\fB--retry\fP \fItimeout\fP|\fIschedule\fP
-With
-.BR --stop ,
-specifies that
-.B start-stop-daemon
-is to check whether the process(es)
-do finish.  It will check repeatedly whether any matching processes
-are running, until none are.  If the processes do not exit it will
-then take further action as determined by the schedule.
-
+.\" Copyright 2007 Roy Marples
+.\" All rights reserved
+.\"
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\" 1. Redistributions of source code must retain the above copyright
+.\"    notice, this list of conditions and the following disclaimer.
+.\" 2. Redistributions in binary form must reproduce the above copyright
+.\"    notice, this list of conditions and the following disclaimer in the
+.\"    documentation and/or other materials provided with the distribution.
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
+.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
+.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
+.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
+.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
+.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
+.\" SUCH DAMAGE.
+.\"
+.Dd Dec 15, 2007
+.Dt START-STOP-DAEMON 8 SMM
+.Os OpenRC
+.Sh NAME
+.Nm start-stop-daemon
+.Nd ensures that daemons start and stop
+.Sh SYNOPSIS
+.Nm
+.Fl S , -start
+.Ar daemon
+.Op Fl -
+.Op Ar arguments
+.Nm
+.Fl K , -stop
+.Ar daemon
+.Nm
+.Fl s , -signal
+.Ar signal
+.Ar daemon
+.Sh DESCRIPTION
+.Nm
+provides a consistent method of starting, stopping and signalling daemons.
+If a daemon cannot background by itself, nor create a pidfile,
+.Nm
+can do it for the daemon in a secure fashion.
+.Nm
+also ensures that a daemon really has started by checking to see if it still
+exists for a short time after it has started. This is because some badly
+written daemons like to daemonize before checking their configuration, doing
+sanity checks, etc. Likewise,
+.Nm
+ensures that a daemon really stops as well, again by using the information
+above to ensure that it's not running.
+.Pp
 If
-.I timeout
-is specified instead of
-.I schedule
-then the schedule
-.IB signal / timeout
-is used, where
-.I signal
-is the signal specified with
-.BR --signal .
-
-.I schedule
-is a list of at least two items separated by slashes
-.RB ( / );
-each item may be
-.BI - signal-number
-or [\fB\-\fP]\fIsignal-name\fP,
-which means to send that signal,
-or
-.IR timeout ,
-which means to wait that many seconds for processes to
-exit,
-or
-.BR forever ,
-which means to repeat the rest of the schedule forever if
-necessary.
-
-If the end of the schedule is reached and
-.BR forever
-is not specified, then
-.B start-stop-daemon
-exits with error status 2.
-If a schedule is specified, then any signal specified
-with
-.B --signal
-is ignored.
-.TP
-.BR -t | --test
-Print actions that would be taken and set appropriate return value,
-but take no action.
-.TP
-.BR -o | --oknodo
-Used for sending signals to a running daemon but not expecting it to stop.
-In this version you can don't need --oknodo if you don't use --stop either.
-.TP
-.BR -q | --quiet
-Do not print informational messages; only display error messages.
-.TP
-\fB-c\fP|\fB--chuid\fP \fIusername\fR|\fIuid\fP
-Change to this username/uid before starting the process. You can also
-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).
-When using this option
-you must realize that the primary and supplemental groups are set as well,
-even if the
-.B --group
-option is not specified.  The
-.B --group
-option is only for
-groups that the user isn't normally a member of (like adding per/process
-group membership for generic users like
-.BR nobody ).
-.TP
-\fB-r\fP|\fB--chroot\fP \fIroot\fP
-Chdir and chroot to
-.I root
-before starting the process. Please note that the pidfile is also written
-after the chroot.
-.TP
-.BR -b | --background
-Typically used with programs that don't detach on their own. This option
-will force
-.B start-stop-daemon
-to fork before starting the process, and force it into the background.
-.TP
-\fB-1\fP|\fB--stdout\fP \fIlogfile\fP
-Redirect the standard output of the process to \fIlogfile\fP when started with
-\fB--background\fP. Must be an absolute pathname, but relative to the
-\fIpath\fP optionally given with \fB--chroot\fP.
-Hint: The \fIlogfile\fP can also be a named pipe.
-.TP
-\fB-2\fP|\fB--stderr\fP \fIlogfile\fP
-The same thing as \fB--stdout\fP but with the standard error output.
-.TP
-.BR -N | --nicelevel
-This alters the prority of the process before starting it. This can also be set
-by the environment variable \fBSSD_NICELEVEL\fR.
-.TP
-.BR -m | --make-pidfile
-Used when starting a program that does not create its own pid file. This
-option will make
-.B start-stop-daemon
-create the file referenced with
-.B --pidfile
-and place the pid into it just before executing the process. Note, it 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
-only useful when combined with the
-.B --background
+.Nm
+is used in an OpenRC service, then OpenRC can in turn check to see if the
+daemon is still running. If not, then the service is marked as crashed.
+.Pp
+Here are the options to specify the daemon and how it should start or stop:
+.Bl -tag -width indent 
+.It Fl x , -exec Ar daemon
+The daemon we start or stop.
+.It Fl p , -pidfile Ar pidfile
+When starting, we expect the daemon to create a valid pidfile within a
+reasonable amount of time. When stopping we only stop the pid(s) listed in
+the pidfile.
+.It Fl n , -name Ar name
+For whatever reason, some daemons don't create pidfiles or change their
+process name. You can specify name here to be the process name to stop.
+You may need to use this for interpreted daemons using languages such as
+perl, ruby, shell, etc.
+.It Fl u , -user Ar user Ns Op : Ns Ar group
+Start the daemon as the user and update $HOME accordingly or stop daemons
+owned by the user. You can optionally append a groupname here also.
+.It Fl t , -test
+Print the action(s) that would be taken, but don't actually do anything.
+The return value is set as if the command was taken and worked.
+.El
+.Pp
+These options are only used for starting daemons:
+.Bl -tag -width indent
+.It Fl b , -background
+Force the daemon into the background. Some daemons don't create pidfiles, so a
+good trick is to get the daemon to run in the foreground, and use the this
+option along with
+.Fl m , -make-pidfile
+to create a working pidfile.
+.It Fl d , -chdir Ar path
+chdir to this directory before starting the daemon.
+.It Fl r , -chroot Ar path
+chroot to this directory before starting the daemon. All other paths, such
+as the path to the daemon, chdir and pidfile, should be relative to the chroot.
+.It Fl g , -group Ar group
+Start the daemon as in the group.
+.It Fl m , -make-pidfile
+Saves the pid of the daemon in the file specified by the
+.Fl p , -pidfile
+option. Only useful when used with daemons that run in the foreground and
+forced into the background with the
+.Fl -b , -background
 option.
-.TP
-.BR -v | --verbose
-Print verbose informational messages.
-.TP
-.BR -H | --help
-Print help information; then exit.
-.TP
-.BR -V | --version
-Print version information; then exit.
+.It Fl n , -nice Ar level
+Modifies the scheduling priority of the daemon.
+.It Fl 1 , -stdout Ar logfile
+Redirect the standard output of the process to logfile when started with
+.Fl background .
+Must be an absolute pathname, but relative to the path optionally given with
+.Fl r , -chroot .
+The logfile can also be a named pipe.
+.It Fl 2 , -stderr Ar logfile
+The same thing as
+.Fl 1 , -stdout
+but with the standard error output.
+.El
+.Pp
+These options are only used for stopping daemons:
+.Bl -tag -width indent
+.It Fl R , -retry Ar timeout | Ar signal Ns / Ns Ar timeout
+You can either specify a timeout or a multiple signal/timeout pairs as a
+stopping schedule.
+If not specified then a default value of SIGTERM/5 is
+assumed.
+.El
+.Sh SEE ALSO
+.Xr chdir 2 ,
+.Xr chroot 2 ,
+.Xr nice 2
+.Sh AUTHORS
+.An "Roy Marples" Aq roy@marples.name