Start documenting rc.subr(8).

There is still space for fixes so we are not linking it to the build yet.

1 files changed, 224 insertions, 0 deletions

diff --git a/share/man/man8/rc.subr.8 b/share/man/man8/rc.subr.8
new file mode 100644
index 00000000000..bfe76912ea9
--- /dev/null
+++ b/share/man/man8/rc.subr.8
@@ -0,0 +1,224 @@
+.\" 	$OpenBSD: rc.subr.8,v 1.1 2011/01/16 13:05:17 robert Exp $
+.\"
+.\" Copyright (c) 2010 Robert Nagy and Antoine Jacoutot
+.\" 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 ``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 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 $Mdocdate: January 16 2011 $
+.Dt RC.SUBR 8
+.Os
+.Sh NAME
+.Nm rc.subr
+.Nd functions used by
+.Xr rc.d 8
+scripts
+.Sh SYNOPSIS
+.Bl -item -compact
+.It
+.Ic .\& Pa /etc/rc.d/rc.subr
+.Pp
+.It
+.Ic rc_cmd Ar argument
+.El
+.Sh DESCRIPTION
+The
+.Nm
+script
+contains commonly used shell script functions and variable
+definitions which are used by various
+.Xr rc.d 8
+scripts.
+.Pp
+The
+.Nm
+functions are accessed by sourcing
+.Pa /etc/rc.d/rc.subr
+into the current shell.
+.Pp
+The following shell functions are available:
+.Bl -tag -width 4n
+.It Ic rc_cmd Ar argument
+Run the
+.Ar argument
+method for the current
+.Xr rc.d 8
+script, based on the settings of various shell variables.
+.Ic rc_cmd
+is extremely flexible, and allows fully functional
+.Xr rc.d 8
+scripts to be implemented in a small amount of shell code.
+For a given method
+.Ar argument ,
+if the
+.Ar rc_${argument}()
+function is not defined, then a default method is provided by
+.Xr rc.subr 8 .
+In addition methods can be disabled by setting the
+.Ar rc_${name}
+variable to
+.Ar NO .
+For example, if rc_reload=NO is set in the
+.Ar rc.d 8
+script, and
+.Ic rc_cmd
+is called with the reload argument, an error will be raised.
+.Pp
+.Ar argument
+is searched for in the list of supported commands, which may be one
+of:
+.Bl -tag -width ".Cm restart" -offset indent
+.It Cm start
+Start the service.
+It checks if the service is already running by calling
+.Ar rc_check
+and refuses to start if it is.
+In addition if the
+.Ar rc_pre()
+function exists, it is going to be called before
+starting the daemon.
+.It Cm stop
+It checks that the service is running by calling
+.Ar rc_check
+and if it's not, no action is going to be taken.
+In addition if the
+.Ar rc_post()
+function exists, it is going to be called right
+after the daemon has been stopped.
+.It Cm reload
+Find the process using
+.Xr pkill 1
+with the regexp specified in the
+.Ar pexp
+variable and send a SIGHUP signal.
+One has to make sure that sending SIGHUP to a daemon will
+have the desired effect, which is reloading the configuration
+files.
+.It Cm restart
+Perform a
+.Cm stop
+then a
+.Cm start .
+.It Cm check
+Return 0 if the daemon is running or 1 if it is not.
+.El
+.Pp
+.Ic rc_cmd
+uses the following shell variables to control its behaviour.
+.Bl -tag -width ".Va procname" -offset indent
+.It Va daemon
+The path to the daemon.
+.It Va daemon_flags
+Arguments to call
+.Va daemon
+with.
+This is usually set in
+.Xr rc.conf 5 ,
+and not in the
+.Xr rc.d 8
+script except when there is a sane default value specified.
+.Ar ${name}_flags
+can be used in
+.Xr rc.conf 5
+to override this.
+.It Va daemon_user
+User to run
+.Va daemon
+as, using
+.Xr su 1 .
+This defaults to root unless specified by the
+.Ar daemon_user
+variable in the
+.Xr rc.d 8
+script or the
+.Ar ${name}_user
+variable in
+.Xr rc.conf 5 .
+.It Va daemon_class
+Login class to run the
+.Va daemon
+with, using
+.Xr su 1 .
+This is a read only variable that gets populated by
+.Xr rc.subr 8
+itself. It searches
+.Xr login.conf 5
+for a login class that has the same name as the
+.Xr rc.d 8
+script itself and uses that. If no such login class
+exists then daemon will be used.
+.It Va daemon_shell
+Shell to run the
+.Va daemon
+in, using
+.Xr su 1 .
+This defaults to /bin/sh unless specified by the
+.Ar daemon_shell
+variable in the
+.Xr rc.d 8
+script or the
+.Ar ${name}_shell
+variable in
+.Xr rc.conf 5 .
+.It Va pexp
+A pattern to be passed to to
+.Xr pgrep 1
+or
+.Xr pkill 1
+in order to find the desired process.
+By default this variable contains the
+.Va daemon
+and
+.Va daemon_flags
+variables.
+.El
+.Sh FILES
+.Bl -tag -width ".Pa /etc/rc.d/rc.subr" -compact
+.It Pa /etc/rc.d/rc.subr
+The
+.Nm
+file resides in
+.Pa /etc/rc.d .
+.It Pa /usr/ports/infrastructure/templates/rc.template
+A sample
+.Xr rc.d 8
+script.
+.El
+.Sh SEE ALSO
+.Xr rc.conf 5 ,
+.Xr rc 8
+.Sh HISTORY
+The
+.Nm
+script
+first appeared in
+.Ox 4.9 .
+.Sh AUTHORS
+.An -nosplit
+The
+.Xr rc.subr 8
+framework was written by
+.An Robert Nagy Aq robert@openbsd.org
+,
+.An Antoine Jacoutot Aq ajacoutot@openbsd.org
+and
+.An Ingo Schwarze Aq schwarze@openbsd.org .