From 933877b6574b82689e571bd3cb41bf4af99caf2c Mon Sep 17 00:00:00 2001 From: ru Date: Fri, 9 Jul 2004 10:08:03 +0000 Subject: Fixed markup. --- share/man/man8/rc.subr.8 | 415 ++++++++++++++++++++++++----------------------- 1 file changed, 216 insertions(+), 199 deletions(-) (limited to 'share/man/man8/rc.subr.8') diff --git a/share/man/man8/rc.subr.8 b/share/man/man8/rc.subr.8 index 10fb533..fa17731 100644 --- a/share/man/man8/rc.subr.8 +++ b/share/man/man8/rc.subr.8 @@ -1,5 +1,4 @@ .\" $NetBSD: rc.subr.8,v 1.12 2004/01/06 00:52:24 lukem Exp $ -.\" $FreeBSD$ .\" .\" Copyright (c) 2002-2004 The NetBSD Foundation, Inc. .\" All rights reserved. @@ -35,6 +34,8 @@ .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE .\" POSSIBILITY OF SUCH DAMAGE. .\" +.\" $FreeBSD$ +.\" .Dd January 6, 2004 .Dt RC.SUBR 8 .Os @@ -42,9 +43,10 @@ .Nm rc.subr .Nd functions used by system shell scripts .Sh SYNOPSIS -.Bl -item +.Bl -item -compact .It -.Li . /etc/rc.subr +.Ic .\& Pa /etc/rc.subr +.Pp .It .Ic backup_file Ar action Ar file Ar current Ar backup .It @@ -66,9 +68,9 @@ .It .Ic mount_critical_filesystems Ar type .It -.Ic rc_usage Ar command Op Ar ... +.Ic rc_usage Ar command ... .It -.Ic reverse_list Ar item Op Ar ... +.Ic reverse_list Ar item ... .It .Ic run_rc_command Ar argument .It @@ -76,12 +78,14 @@ .It .Ic set_rcvar Op Ar base .It -.Ic wait_for_pids Op Ar pid Op Ar ... +.Ic wait_for_pids Op Ar pid ... .It .Ic warn Ar message .El .Sh DESCRIPTION +The .Nm +script contains commonly used shell script functions and variable definitions which are used by various scripts such as .Xr rc 8 . @@ -100,21 +104,23 @@ With that in mind there are several variable definitions that can help in this regard. They are: .Bl -tag -width 4n -.It Ic OSTYPE +.It Va OSTYPE Its value will be either -.Fx +.Qq Li FreeBSD or -.Nx , +.Qq Li NetBSD , depending on which OS it is running on. -.It Ic SYSCTL +.It Va SYSCTL The path to the .Xr sysctl 8 command. -.It Ic SYSCTL_N +.It Va SYSCTL_N The path and argument list to display only the .Xr sysctl 8 -values instead of a name=value pair. -.It Ic SYSCTL_W +values instead of a +.Ar name Ns = Ns Ar value +pair. +.It Va SYSCTL_W The path and argument to write or modify .Xr sysctl 8 values. @@ -128,9 +134,7 @@ into the current shell. .Pp The following shell functions are available: .Bl -tag -width 4n -.It Xo -.Ic backup_file Ar action Ar file Ar current Ar backup -.Xc +.It Ic backup_file Ar action file current backup Make a backup copy of .Ar file into @@ -138,9 +142,9 @@ into If the .Xr rc.conf 5 variable -.Sy backup_uses_rcs +.Va backup_uses_rcs is -.Sq YES , +.Dq Li YES , use .Xr rcs 1 to archive the previous version of @@ -150,17 +154,19 @@ otherwise save the previous version of as .Ar backup . .Pp +The .Ar action +argument may be one of the following: -.Bl -tag -width remove -.It Sy add +.Bl -tag -width ".Cm remove" +.It Cm add .Ar file is now being backed up by or possibly re-entered into this backup mechanism. .Ar current is created, and if necessary, the .Xr rcs 1 files are created as well. -.It Sy update +.It Cm update .Ar file has changed and needs to be backed up. If @@ -174,7 +180,7 @@ and then .Ar file is copied to .Ar current . -.It Sy remove +.It Cm remove .Ar file is no longer being tracked by this backup mechanism. If @@ -191,29 +197,24 @@ is moved to Return 0 if .Ar var is defined to -.Sq YES , -.Sq TRUE , -.Sq ON , +.Dq Li YES , +.Dq Li TRUE , +.Dq Li ON , or -.Sq 1 . +.Ql 1 . Return 1 if .Ar var is defined to -.Sq NO , -.Sq FALSE , -.Sq OFF , +.Dq Li NO , +.Dq Li FALSE , +.Dq Li OFF , or -.Sq 0 . +.Ql 0 . Otherwise, warn that .Ar var is not set correctly. The values are case insensitive. -.It Xo -.Ic check_pidfile -.Ar pidfile -.Ar procname -.Op Ar interpreter -.Xc +.It Ic check_pidfile Ar pidfile procname Op Ar interpreter Parses the first word of the first line of .Ar pidfile for a PID, and ensures that the process with that PID @@ -225,7 +226,9 @@ If is provided, parse the first line of .Ar procname , ensure that the line is of the form -.Dl #! interpreter [...] +.Pp +.Dl "#! interpreter [...]" +.Pp and use .Ar interpreter with its optional arguments and @@ -240,16 +243,16 @@ is handled as per .Ic check_pidfile . .It Ic debug Ar message Display a debugging message to -.Em stderr , +.Va stderr , log it to the system log using .Xr logger 1 , and return to the caller. The error message consists of the script name (from -.Sy $0 ) , +.Va $0 ) , followed by -.Dq ": DEBUG: " , +.Dq Li ": DEBUG: " , and then .Ar message . This function is intended to be used by developers @@ -258,22 +261,22 @@ It can be turned on or off by the .Xr rc.conf 5 variable -.Em rc_debug . -.It Ic err Ar exitval Ar message +.Va rc_debug . +.It Ic err Ar exitval message Display an error message to -.Em stderr , +.Va stderr , log it to the system log using .Xr logger 1 , and -.Cm exit +.Ic exit with an exit value of .Ar exitval . The error message consists of the script name (from -.Sy $0 ) , +.Va $0 ) , followed by -.Dq ": ERROR: " , +.Dq Li ": ERROR: " , and then .Ar message . .It Ic force_depend name @@ -283,30 +286,30 @@ service to start. The .Ar name argument is the -.Xr basename 1 , +.Xr basename 1 component of the path to the script, usually -.Em /etc/rc.d/name . +.Pa /etc/rc.d/name . If the script fails for any reason it will output a warning and return with a return value of 1. If it was successful it will return 0. .It Ic info Ar message Display an informational message to -.Em stdout , +.Va stdout , and log it to the system log using .Xr logger 1 . The message consists of the script name (from -.Sy $0 ) , +.Va $0 ) , followed by -.Dq ": INFO: " , +.Dq Li ": INFO: " , and then .Ar message . The display of this informational output can be turned on or off by the .Xr rc.conf 5 variable -.Em rc_info . +.Va rc_info . .It Ic load_rc_config Ar command Source in the configuration files for .Ar command . @@ -327,18 +330,20 @@ Go through a list of critical file systems, as found in the .Xr rc.conf 5 variable -.Sy critical_filesystems_ Ns Ar type , +.Va critical_filesystems_ Ns Ar type , mounting each one that is not currently mounted. -.It Ic rc_usage Ar command Op Ar ... +.It Ic rc_usage Ar command ... Print a usage message for -.Sy $0 , +.Va $0 , with .Ar commands being the list of valid arguments prefixed by -.Dq "[fast|force|one]" . -.It Ic reverse_list Ar item Op Ar ... +.Sm off +.Dq Bq Li fast | force | one . +.Sm on +.It Ic reverse_list Ar item ... Print the list of .Ar items in reverse order. @@ -356,8 +361,8 @@ scripts to be implemented in a small amount of shell code. .Ar argument is searched for in the list of supported commands, which may be one of: -.Bl -tag -width restart -offset indent -.It Sy start +.Bl -tag -width ".Cm restart" -offset indent +.It Cm start Start the service. This should check that the service is to be started as specified by .Xr rc.conf 5 . @@ -367,143 +372,153 @@ This latter check is not performed by standard .Fx scripts if the system is starting directly to multi-user mode, to speed up the boot process. -.It Sy stop +.It Cm stop If the service is to be started as specified by .Xr rc.conf 5 , stop the service. -This should check that the service is running and complain if it's not. -.It Sy restart +This should check that the service is running and complain if it is not. +.It Cm restart Perform a -.Sy stop +.Cm stop then a -.Sy start . +.Cm start . Defaults to displaying the process ID of the program (if running). -.It Sy rcvar +.It Cm rcvar Display which .Xr rc.conf 5 variables are used to control the startup of the service (if any). .El .Pp If -.Sy pidfile +.Va pidfile or -.Sy procname +.Va procname is set, also support: -.Bl -tag -width restart -offset indent -.It Sy poll +.Bl -tag -width ".Cm restart" -offset indent +.It Cm poll Wait for the command to exit. -.It Sy status +.It Cm status Show the status of the process. .El .Pp Other supported commands are listed in the optional variable -.Sy extra_commands . +.Va extra_commands . .Pp .Ar argument may have one of the following prefixes which alters its operation: -.Bl -tag -width "Prefix" -offset indent -.It Sy fast +.Bl -tag -width ".Li force" -offset indent +.It Li fast Skip the check for an existing running process, and sets -.Sy rc_fast=YES . -.It Sy force +.Va rc_fast Ns = Ns Li YES . +.It Li force Skip the checks for -.Sy rcvar -being set to yes, +.Va rcvar +being set to +.Dq Li YES , and sets -.Sy rc_force=YES . +.Va rc_force Ns = Ns Li YES . This ignores -.Ar argument Ns Sy _precmd +.Ar argument Ns Va _precmd returning non-zero, and ignores any of the -.Sy required_* +.Va required_* tests failing, and always returns a zero exit status. -.It Sy one +.It Li one Skip the checks for -.Sy rcvar -being set to yes, but performs all the other prerequisite tests. +.Va rcvar +being set to +.Dq Li YES , +but performs all the other prerequisite tests. .El .Pp .Ic run_rc_command uses the following shell variables to control its behaviour. Unless otherwise stated, these are optional. -.Bl -tag -width procname -offset indent -.It Sy name +.Bl -tag -width ".Va procname" -offset indent +.It Va name The name of this script. This is not optional. -.It Sy rcvar +.It Va rcvar The value of -.Sy rcvar +.Va rcvar is checked with .Ic checkyesno to determine if this method should be run. -.It Sy command +.It Va command Full path to the command. Not required if -.Ar argument Ns Sy _cmd +.Ar argument Ns Va _cmd is defined for each supported keyword. -.It Sy command_args +.It Va command_args Optional arguments and/or shell directives for -.Sy command . -.It Sy command_interpreter -.Sy command +.Va command . +.It Va command_interpreter +.Va command is started with -.Dl #! command_interpreter [...] +.Pp +.Dl "#! command_interpreter [...]" which results in its .Xr ps 1 command being -.Dl command_interpreter [...] command +.Pp +.Dl "command_interpreter [...] command" +.Pp so use that string to find the PID(s) of the running command rather than -.Ql command . -.It Sy extra_commands +.Va command . +.It Va extra_commands Extra commands/keywords/arguments supported. -.It Sy pidfile -Path to pid file. +.It Va pidfile +Path to PID file. Used to determine the PID(s) of the running command. If -.Sy pidfile +.Va pidfile is set, use -.Dl check_pidfile $pidfile $procname +.Pp +.Dl "check_pidfile $pidfile $procname" +.Pp to find the PID. Otherwise, if -.Sy command +.Va command is set, use -.Dl check_process $procname +.Pp +.Dl "check_process $procname" +.Pp to find the PID. -.It Sy procname +.It Va procname Process name to check for. Defaults to the value of -.Sy command . -.It Sy required_dirs +.Va command . +.It Va required_dirs Check for the existence of the listed directories before running the default start method. -.It Sy required_files +.It Va required_files Check for the readability of the listed files before running the default start method. -.It Sy required_vars +.It Va required_vars Perform .Ic checkyesno on each of the list variables before running the default start method. -.It Sy ${name}_chdir +.It Va ${name}_chdir Directory to .Ic cd to before running -.Sy command , +.Va command , if -.Sy ${name}_chroot +.Va ${name}_chroot is not provided. -.It Sy ${name}_chroot +.It Va ${name}_chroot Directory to .Xr chroot 8 to before running -.Sy command . +.Va command . Only supported after .Pa /usr is mounted. -.It Sy ${name}_flags +.It Va ${name}_flags Arguments to call -.Sy command +.Va command with. This is usually set in .Xr rc.conf 5 , @@ -513,63 +528,63 @@ script. The environment variable .Sq Ev flags can be used to override this. -.It Sy ${name}_nice +.It Va ${name}_nice .Xr nice 1 level to run -.Sy command +.Va command as. Only supported after .Pa /usr is mounted. -.It Sy ${name}_user +.It Va ${name}_user User to run -.Sy command +.Va command as, using .Xr chroot 8 . if -.Sy ${name}_chroot +.Va ${name}_chroot is set, otherwise uses .Xr su 1 . Only supported after .Pa /usr is mounted. -.It Sy ${name}_group +.It Va ${name}_group Group to run the chrooted -.Sy command +.Va command as. -.It Sy ${name}_groups +.It Va ${name}_groups Comma separated list of supplementary groups to run the chrooted -.Sy command +.Va command with. -.It Ar argument Ns Sy _cmd +.It Ar argument Ns Va _cmd Shell commands which override the default method for .Ar argument . -.It Ar argument Ns Sy _precmd +.It Ar argument Ns Va _precmd Shell commands to run just before running -.Ar argument Ns Sy _cmd +.Ar argument Ns Va _cmd or the default method for .Ar argument . If this returns a non-zero exit code, the main method is not performed. If the default method is being executed, this check is performed after the -.Sy required_* +.Va required_* checks and process (non-)existence checks. -.It Ar argument Ns Sy _postcmd +.It Ar argument Ns Va _postcmd Shell commands to run if running -.Ar argument Ns Sy _cmd +.Ar argument Ns Va _cmd or the default method for .Ar argument returned a zero exit code. -.It Sy sig_stop +.It Va sig_stop Signal to send the processes to stop in the default -.Sy stop +.Cm stop method. Defaults to .Dv SIGTERM . -.It Sy sig_reload +.It Va sig_reload Signal to send the processes to reload in the default -.Sy reload +.Cm reload method. Defaults to .Dv SIGHUP . @@ -578,96 +593,96 @@ Defaults to For a given method .Ar argument , if -.Ar argument Ns Sy _cmd +.Ar argument Ns Va _cmd is not defined, then a default method is provided by -.Sy run_rc_command : -.Bl -tag -width "argument" -offset indent +.Ic run_rc_command : +.Bl -tag -width ".Sy Argument" -offset indent .It Sy Argument .Sy Default method -.It Sy start +.It Cm start If -.Sy command +.Va command is not running and -.Ic checkyesno Sy rcvar +.Ic checkyesno Va rcvar succeeds, start -.Sy command . -.It Sy stop +.Va command . +.It Cm stop Determine the PIDs of -.Sy command +.Va command with .Ic check_pidfile or .Ic check_process (as appropriate), -.Ic kill Sy sig_stop +.Ic kill Va sig_stop those PIDs, and run .Ic wait_for_pids on those PIDs. -.It Sy reload +.It Cm reload Similar to -.Sy stop , +.Cm stop , except that it uses -.Sy sig_reload -instead, and doesn't run +.Va sig_reload +instead, and does not run .Ic wait_for_pids . -.It Sy restart +.It Cm restart Runs the -.Sy stop +.Cm stop method, then the -.Sy start +.Cm start method. -.It Sy status +.It Cm status Show the PID of -.Sy command , +.Va command , or some other script specific status operation. -.It Sy poll +.It Cm poll Wait for -.Sy command +.Va command to exit. -.It Sy rcvar +.It Cm rcvar Display which .Xr rc.conf 5 variable is used (if any). This method always works, even if the appropriate .Xr rc.conf 5 variable is set to -.Sq NO . +.Dq Li NO . .El .Pp The following variables are available to the methods (such as -.Ar argument Ns Sy _cmd ) +.Ar argument Ns Va _cmd ) as well as after .Ic run_rc_command has completed: -.Bl -tag -width "rc_flags" -offset indent -.It Sy rc_arg +.Bl -tag -width ".Va rc_flags" -offset indent +.It Va rc_arg Argument provided to -.Sy run_rc_command , +.Ic run_rc_command , after fast and force processing has been performed. -.It Sy rc_flags +.It Va rc_flags Flags to start the default command with. Defaults to -.Sy ${name}_flags , +.Va ${name}_flags , unless overridden by the environment variable .Sq Ev flags . This variable may be changed by the -.Ar argument Ns Sy _precmd +.Ar argument Ns Va _precmd method. -.It Sy rc_pid +.It Va rc_pid PID of -.Sy command +.Va command (if appropriate). -.It Sy rc_fast +.It Va rc_fast Not empty if -.Dq fast +.Dq Li fast prefix was used. -.It Sy rc_force +.It Va rc_force Not empty if -.Dq force +.Dq Li force prefix was used. .El -.It Ic run_rc_script Ar file Ar argument +.It Ic run_rc_script Ar file argument Start the script .Ar file with an argument of @@ -678,19 +693,19 @@ Various shell variables are unset before .Ar file is started: .Bd -ragged -offset indent -.Sy name , -.Sy command , -.Sy command_args , -.Sy command_interpreter , -.Sy extra_commands , -.Sy pidfile , -.Sy rcvar , -.Sy required_dirs , -.Sy required_files , -.Sy required_vars , -.Ar argument Ns Sy _cmd , -.Ar argument Ns Sy _precmd . -.Ar argument Ns Sy _postcmd . +.Va name , +.Va command , +.Va command_args , +.Va command_interpreter , +.Va extra_commands , +.Va pidfile , +.Va rcvar , +.Va required_dirs , +.Va required_files , +.Va required_vars , +.Ar argument Ns Va _cmd , +.Ar argument Ns Va _precmd . +.Ar argument Ns Va _postcmd . .Ed .Pp The startup behaviour of @@ -708,11 +723,9 @@ If .Ar file appears to be a backup or scratch file (e.g., with a suffix of -.Sq ~ , -.Sq # , -.Sq .OLD , +.Pa ~ , # , .OLD , or -.Sq .orig ) , +.Pa .orig ) , ignore it. .It If @@ -722,7 +735,7 @@ is not executable, ignore it. If the .Xr rc.conf 5 variable -.Sy rc_fast_and_loose +.Va rc_fast_and_loose is empty, source .Ar file @@ -738,15 +751,15 @@ In a daemon is usually controlled by an .Xr rc.conf 5 variable consisting of a daemon's name postfixed by the string -.Sy "_enable" . +.Dq Li "_enable" . This is not the case in .Nx . When the following line is included in a script .Pp -.Dl rcvar=`set_rcvar` +.Dl "rcvar=`set_rcvar`" .Pp This function will use the value of the -.Sy $name +.Va $name variable, which should be defined by the calling script, to construct the appropriate .Xr rc.conf 5 knob. @@ -755,29 +768,29 @@ If the argument is set it will use .Ar base instead of -.Sy $name . -.It Ic wait_for_pids Op Ar pid Op Ar ... +.Va $name . +.It Ic wait_for_pids Op Ar pid ... Wait until all of the provided .Ar pids -don't exist any more, printing the list of outstanding +do not exist any more, printing the list of outstanding .Ar pids every two seconds. .It Ic warn Ar message Display a warning message to -.Em stderr +.Va stderr and log it to the system log using .Xr logger 1 . The warning message consists of the script name (from -.Sy $0 ) , +.Va $0 ) , followed by -.Dq ": WARNING: " , +.Dq Li ": WARNING: " , and then .Ar message . .El .Sh FILES -.Bl -tag -width /etc/rc.subr -compact +.Bl -tag -width ".Pa /etc/rc.subr" -compact .It Pa /etc/rc.subr The .Nm @@ -788,13 +801,17 @@ file resides in .Xr rc.conf 5 , .Xr rc 8 .Sh HISTORY +The .Nm +script appeared in .Nx 1.3 . The .Xr rc.d 8 support functions appeared in .Nx 1.5 . +The .Nm +script first appeared in .Fx 5.0 . -- cgit v1.1