Document the rc.d system.

Suggested by:	dcs
Reviewed by:	alex, dcs, sheldonh

share/man/man8/rc.8

@@ -42,6 +42,7 @@
 .Nm rc
 .Nm rc.conf
 .Nm rc.conf.local
+.Nm rc.d
 .Nm rc.serial
 .Nm rc.pccard
 .Nm rc.network
@@ -67,6 +68,72 @@ by the rc files, while
 .Nm rc.conf.local
 contains the local system configuration.  See rc.conf(5)
 .Pp
+The
+.Nm rc.d
+directories contain scripts which will be automatically
+executed at boot time and shutdown time.
+At boot time,
+the specified directories are processed immediately after
+.Nm rc.local
+is executed.
+(See below for details on how to specify directories to check.)
+At shutdown time,
+the directories are processed by
+.Nm rc.shutdown .
+The following key points apply to the scripts within each directory:
+.Pp
+.Bl -bullet -compact
+.It
+Scripts are only executed if their
+.Xr basename 1
+matches the shell globbing pattern
+.Pa *.sh ,
+and they are executable.
+Any other files or directories present within the directory are silently
+ignored.
+.It
+When a script is executed at boot time, it is passed the string
+.Dq start
+as its first and only argument.
+At shutdown time, it is passed the string
+.Dq stop
+as its first and only argument.
+All
+.Nm rc.d
+scripts expected to handle these arguments appropriately.
+If no action needs to be taken at a given time
+(either boot time or shutdown time)
+the script should exit successfully and without producing an error message.
+.It
+The scripts within each directory are executed in lexicographical order.
+If a specific order is required,
+numbers may be used as a prefix to the existing filenames,
+so for example
+.Pa 100.foo
+would be executed before
+.Pa 200.bar ;
+without the numeric prefixes the opposite would be true.
+.El
+.Pp
+The output from each script is traditionally a space character,
+followed by the name of the software package being started or shut down,
+.Em without
+a trailing newline character (see the
+.Sx EXAMPLES
+section).
+.Pp
+The system initialization scripts can execute scripts from multiple
+.Nm rc.d
+directories.
+The default locations are
+.Pa /usr/local/etc/rc.d
+and
+.Pa /usr/X11R6/etc/rc.d ,
+but these may be overridden with the
+.Va local_startup
+.Xr rc.conf 5
+variable.
+.Pp
 .Nm Rc.shutdown
 is the command script which contains any necessary commands
 to be executed as the system is shut down.
@@ -155,7 +222,37 @@ by the administrator.
 .Pp
 Following tradition, the startup files reside in
 .Pa /etc .
+.Sh EXAMPLES
+The following is a simple, hypothetical example of an
+.Nm rc.d
+script,
+which would start a daemon at boot time,
+and kill it at shutdown time.
+.Bd -literal -offset indent
+#!/bin/sh -
+#
+#    initialization/shutdown script for foobar package
+
+case "$1" in
+start)
+	/usr/local/sbin/foo -d && echo -n ' foo'
+	;;
+stop)
+	kill `cat /var/run/foo.pid` && echo -n ' foo'
+	;;
+*)
+	echo "unknown option: $1 - should be 'start' or 'stop'" >&2
+	;;
+esac
+.Ed
+.Pp
+As all processes are killed by
+.Xr init 8
+at shutdown, the explicit
+.Xr kill 1
+is unnecessary, but is often included.
 .Sh SEE ALSO
+.Xr kill 1 ,
 .Xr rc.conf 5 ,
 .Xr init 8 ,
 .Xr reboot 8 ,