866 lines
19 KiB
Groff
866 lines
19 KiB
Groff
.\" $NetBSD: rc.subr.8,v 1.31 2012/12/18 13:14:34 wiz Exp $
|
|
.\"
|
|
.\" Copyright (c) 2002-2011 The NetBSD Foundation, Inc.
|
|
.\" All rights reserved.
|
|
.\"
|
|
.\" This code is derived from software contributed to The NetBSD Foundation
|
|
.\" by Luke Mewburn.
|
|
.\"
|
|
.\" 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 NETBSD FOUNDATION, INC. 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 FOUNDATION 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 December 17, 2012
|
|
.Dt RC.SUBR 8
|
|
.Os
|
|
.Sh NAME
|
|
.Nm rc.subr
|
|
.Nd functions used by system shell scripts
|
|
.Sh SYNOPSIS
|
|
.Bl -item
|
|
.It
|
|
.Li . /etc/rc.subr
|
|
.It
|
|
.Ic backup_file Ar action Ar file Ar current Ar backup
|
|
.It
|
|
.Ic basename Ar file Op Ar suffix
|
|
.It
|
|
.Ic checkyesno Ar var
|
|
.It
|
|
.Ic check_pidfile Ar pidfile Ar procname Op Ar interpreter
|
|
.It
|
|
.Ic check_process Ar procname Op Ar interpreter
|
|
.It
|
|
.Ic collapse_backslash_newline
|
|
.It
|
|
.Ic dirname Ar file
|
|
.It
|
|
.Ic err Ar exitval Ar message
|
|
.It
|
|
.Ic load_rc_config Ar command
|
|
.It
|
|
.Ic load_rc_config_var Ar command Ar var
|
|
.It
|
|
.Ic mount_critical_filesystems Ar type
|
|
.It
|
|
.Ic no_rc_postprocess Ar command Op Ar arguments
|
|
.It
|
|
.Ic print_rc_metadata Ar string
|
|
.It
|
|
.Ic print_rc_normal Oo Fl n Oc Ar string
|
|
.It
|
|
.Ic rc_usage Ar command Op Ar ...
|
|
.It
|
|
.Ic reverse_list Ar item Op Ar ...
|
|
.It
|
|
.Ic run_rc_command Ar argument [parameters]
|
|
.It
|
|
.Ic run_rc_script Ar file Ar argument
|
|
.It
|
|
.Ic stop_boot
|
|
.It
|
|
.Ic twiddle
|
|
.It
|
|
.Ic wait_for_pids Op Ar pid Op Ar ...
|
|
.It
|
|
.Ic warn Ar message
|
|
.It
|
|
.Ic yesno_to_truefalse Ar var
|
|
.El
|
|
.Sh DESCRIPTION
|
|
.Nm
|
|
contains commonly used shell script functions which are used by
|
|
various scripts such as
|
|
.Xr rc 8 ,
|
|
and the periodic system services which are controlled by
|
|
.Xr daily.conf 5 ,
|
|
.Xr monthly.conf 5 ,
|
|
.Xr security.conf 5 ,
|
|
and
|
|
.Xr weekly.conf 5 .
|
|
.Pp
|
|
The
|
|
.Nm
|
|
functions are accessed by sourcing
|
|
.Pa /etc/rc.subr
|
|
into the current shell.
|
|
.Pp
|
|
The following shell functions are available:
|
|
.Bl -tag -width 4n
|
|
.It Ic backup_file Ar action Ar file Ar current Ar backup
|
|
Make a backup copy of
|
|
.Ar file
|
|
into
|
|
.Ar current .
|
|
If the
|
|
.Xr rc.conf 5
|
|
variable
|
|
.Sy backup_uses_rcs
|
|
is
|
|
.Sq YES ,
|
|
use
|
|
.Xr rcs 1
|
|
to archive the previous version of
|
|
.Ar current ,
|
|
otherwise save the previous version of
|
|
.Ar current
|
|
as
|
|
.Ar backup .
|
|
.Pp
|
|
.Ar action
|
|
may be one of the following:
|
|
.Bl -tag -width remove
|
|
.It Sy 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
|
|
.Ar file
|
|
has changed and needs to be backed up.
|
|
If
|
|
.Ar current
|
|
exists, it is copied to
|
|
.Ar backup
|
|
or checked into
|
|
.Xr rcs 1
|
|
(if the repository file is old),
|
|
and then
|
|
.Ar file
|
|
is copied to
|
|
.Ar current .
|
|
.It Sy remove
|
|
.Ar file
|
|
is no longer being tracked by this backup mechanism.
|
|
If
|
|
.Xr rcs 1
|
|
is being used, an empty file is checked in and
|
|
.Ar current
|
|
is removed,
|
|
otherwise
|
|
.Ar current
|
|
is moved to
|
|
.Ar backup .
|
|
.El
|
|
.Ic basename Ar file Op Ar suffix
|
|
Just like
|
|
.Xr basename 1 ,
|
|
except implemented using shell built-in commands, and usable before the
|
|
.Pa /usr/bin
|
|
direcory is available.
|
|
.It Ic checkyesno Ar var
|
|
Return 0 if
|
|
.Ar var
|
|
is defined to
|
|
.Sq YES ,
|
|
.Sq TRUE ,
|
|
.Sq ON ,
|
|
or
|
|
.Sq 1 .
|
|
Return 1 if
|
|
.Ar var
|
|
is defined to
|
|
.Sq NO ,
|
|
.Sq FALSE ,
|
|
.Sq OFF ,
|
|
or
|
|
.Sq 0 .
|
|
Otherwise, warn that
|
|
.Ar var
|
|
is not set correctly.
|
|
The values are case insensitive.
|
|
.Pp
|
|
Note that the warning message shown by this function when
|
|
.Ar var
|
|
is not set references a manual page where the user can find more information.
|
|
Its name is picked up from the
|
|
.Sy rcvar_manpage
|
|
variable.
|
|
.It Ic check_pidfile Ar pidfile Ar 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
|
|
is running and its first argument matches
|
|
.Ar procname .
|
|
Prints the matching PID if successful, otherwise nothing.
|
|
If
|
|
.Ar interpreter
|
|
is provided, parse the first line of
|
|
.Ar procname ,
|
|
ensure that the line is of the form
|
|
.Dl #! interpreter [...]
|
|
and use
|
|
.Ar interpreter
|
|
with its optional arguments and
|
|
.Ar procname
|
|
appended as the process string to search for.
|
|
.It Ic check_process Ar procname Op Ar interpreter
|
|
Prints the PIDs of any processes that are running with a first
|
|
argument that matches
|
|
.Ar procname .
|
|
.Ar interpreter
|
|
is handled as per
|
|
.Ic check_pidfile .
|
|
.It Ic collapse_backslash_newline
|
|
Copy input to output, collapsing
|
|
.Ao backslash Ac Ns Ao newline Ac
|
|
to nothing, but leaving other backslashes alone.
|
|
.Ic dirname Ar file
|
|
Just like
|
|
.Xr dirname 1 ,
|
|
except implemented using shell built-in commands, and usable before the
|
|
.Pa /usr/bin
|
|
direcory is available.
|
|
.It Ic err Ar exitval Ar message
|
|
Display an error message to
|
|
.Em stderr ,
|
|
log it to the system log
|
|
using
|
|
.Xr logger 1 ,
|
|
and
|
|
.Cm exit
|
|
with an exit value of
|
|
.Ar exitval .
|
|
The error message consists of the script name
|
|
(from
|
|
.Sy $0 ) ,
|
|
followed by
|
|
.Dq ": ERROR: " ,
|
|
and then
|
|
.Ar message .
|
|
.It Ic load_rc_config Ar command
|
|
Source in the
|
|
.Xr rc.conf 5
|
|
configuration files for
|
|
.Ar command .
|
|
First,
|
|
.Pa /etc/rc.conf
|
|
is sourced if it has not yet been read in.
|
|
Then,
|
|
.Pa /etc/rc.conf.d/ Ns Ar command
|
|
is sourced if it is an existing file.
|
|
The latter may also contain other variable assignments to override
|
|
.Ic run_rc_command
|
|
arguments defined by the calling script, to provide an easy
|
|
mechanism for an administrator to override the behaviour of a given
|
|
.Xr rc.d 8
|
|
script without requiring the editing of that script.
|
|
.It Ic load_rc_config_var Ar command Ar var
|
|
Read the
|
|
.Xr rc.conf 5
|
|
variable
|
|
.Ar var
|
|
for
|
|
.Ar command
|
|
and set in the current shell, using
|
|
.Ic load_rc_config
|
|
in a sub-shell to prevent unwanted side effects from other variable
|
|
assignments.
|
|
.It Ic mount_critical_filesystems Ar type
|
|
Go through a list of critical file systems,
|
|
as found in the
|
|
.Xr rc.conf 5
|
|
variable
|
|
.Sy critical_filesystems_ Ns Ar type ,
|
|
mounting each one that
|
|
is not currently mounted.
|
|
.It Ic no_rc_postprocess Ar command Op Ar arguments
|
|
Execute the specified command with the specified arguments,
|
|
in such a way that its output bypasses the post-processor that
|
|
.Xr rc 8
|
|
uses for most commands.
|
|
This implies that the output will not appear in the
|
|
.Pa /var/run/rc.log
|
|
file, and will appear on the console regardless of the
|
|
value of
|
|
.Va rc_silent .
|
|
This is expected to be useful for interactive commands,
|
|
and this mechanism is automatically used by
|
|
.Ic run_rc_command
|
|
when a script contains the
|
|
.Xr rcorder 8
|
|
keyword
|
|
.Dq interactive .
|
|
.Pp
|
|
If invoked from a context that does not appear to be under the control of
|
|
.Xr rc 8 ,
|
|
then the command is executed without special treatment.
|
|
.It Ic print_rc_metadata Ar string
|
|
Print the specified
|
|
.Ar string
|
|
in such a way that it should be handled as meta-data by the
|
|
.Xr rc 8
|
|
post-processor.
|
|
If invoked from a context that does not appear to be under the control of
|
|
.Xr rc 8 ,
|
|
then the
|
|
.Ar string
|
|
is discarded.
|
|
.Pp
|
|
Any
|
|
.Xr rc.d 8
|
|
script may invoke this function with an argument that begins with
|
|
.Dq note: ,
|
|
followed by one line of arbitrary text;
|
|
the text will be logged by
|
|
.Xr rc 8
|
|
but will not be displayed on the console.
|
|
.Pp
|
|
The use of arguments that do not begin with
|
|
.Dq note:
|
|
is reserved for internal use by
|
|
.Xr rc 8
|
|
and
|
|
.Nm .
|
|
.It Ic print_rc_normal Oo Fl n Oc Ar string
|
|
Print the specified
|
|
.Ar string
|
|
in such a way that it should be handled as normal output by the
|
|
.Xr rc 8
|
|
post-processor.
|
|
If invoked from a context that does not appear to be under the control of
|
|
.Xr rc 8 ,
|
|
then the
|
|
.Ar string
|
|
is printed to standard output.
|
|
.Pp
|
|
If the
|
|
.Fl n
|
|
flag is specified, then the string is printed without a newline.
|
|
.Pp
|
|
Intended use cases include:
|
|
.Bl -bullet
|
|
.It
|
|
An rc.d script can use
|
|
.Dq Sy print_rc_normal Fl n
|
|
to print a partial line in such a way that it appears
|
|
immediately instead of being buffered by
|
|
.Xr rc 8 Ap s
|
|
post-processor.
|
|
.It
|
|
An rc.d script that is run via the
|
|
.Sy no_rc_postprocess
|
|
function (so most of its output is invisible to
|
|
.Xr rc 8 Ap s
|
|
post-processor) can use
|
|
.Sy print_rc_normal
|
|
to force some of its output to be seen by the post-processor.
|
|
.El
|
|
.It Ic rc_usage Ar command Op Ar ...
|
|
Print a usage message for
|
|
.Sy $0 ,
|
|
with
|
|
.Ar commands
|
|
being the list of valid arguments
|
|
prefixed by
|
|
.Dq "[fast|force|one]" .
|
|
.It Ic reverse_list Ar item Op Ar ...
|
|
Print the list of
|
|
.Ar items
|
|
in reverse order.
|
|
.It Ic run_rc_command Ar argument Op Ar parameter ...
|
|
Run the
|
|
.Ar argument
|
|
method for the current
|
|
.Xr rc.d 8
|
|
script, based on the settings of various shell variables.
|
|
.Ic run_rc_command
|
|
is extremely flexible, and allows fully functional
|
|
.Xr rc.d 8
|
|
scripts to be implemented in a small amount of shell code.
|
|
The optional set of parameters is passed verbatim to the command, but not to its
|
|
pre/post hooks.
|
|
.Pp
|
|
.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
|
|
Start the service.
|
|
This should check that the service is to be started as specified by
|
|
.Xr rc.conf 5 .
|
|
Also checks if the service is already running and refuses to start if
|
|
it is.
|
|
This latter check is not performed by standard
|
|
.Nx
|
|
scripts if the system is starting directly to multi-user mode, to
|
|
speed up the boot process.
|
|
.It Sy 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
|
|
Perform a
|
|
.Sy stop
|
|
then a
|
|
.Sy start .
|
|
Defaults to displaying the process ID of the program (if running).
|
|
.It Sy rcvar
|
|
Display which
|
|
.Xr rc.conf 5
|
|
variables are used to control the startup of the service (if any).
|
|
.El
|
|
.Pp
|
|
If
|
|
.Sy pidfile
|
|
or
|
|
.Sy procname
|
|
is set, also support:
|
|
.Bl -tag -width restart -offset indent
|
|
.It Sy poll
|
|
Wait for the command to exit.
|
|
.It Sy status
|
|
Show the status of the process.
|
|
.El
|
|
.Pp
|
|
Other supported commands are listed in the optional variable
|
|
.Sy 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
|
|
Skip the check for an existing running process,
|
|
and sets
|
|
.Sy rc_fast=YES .
|
|
.It Sy force
|
|
Skip the checks for
|
|
.Sy rcvar
|
|
being set to yes,
|
|
and sets
|
|
.Sy rc_force=YES .
|
|
This ignores
|
|
.Ar argument Ns Sy _precmd
|
|
returning non-zero, and ignores any of the
|
|
.Sy required_*
|
|
tests failing, and always returns a zero exit status.
|
|
.It Sy one
|
|
Skip the checks for
|
|
.Sy rcvar
|
|
being set to 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
|
|
The name of this script.
|
|
This is not optional.
|
|
.It Sy rcvar
|
|
The value of
|
|
.Sy rcvar
|
|
is checked with
|
|
.Ic checkyesno
|
|
to determine if this method should be run.
|
|
.It Sy rcvar_manpage
|
|
The manual page containing information about
|
|
.Sy rcvar .
|
|
It will be part of the warning message shown when
|
|
.Sy rcvar
|
|
is undefined.
|
|
Defaults to
|
|
.Xr rc.conf 5 .
|
|
.It Sy command
|
|
Full path to the command.
|
|
Not required if
|
|
.Ar argument Ns Sy _cmd
|
|
is defined for each supported keyword.
|
|
.It Sy command_args
|
|
Optional arguments and/or shell directives for
|
|
.Sy command .
|
|
.It Sy command_interpreter
|
|
.Sy command
|
|
is started with
|
|
.Dl #! command_interpreter [...]
|
|
which results in its
|
|
.Xr ps 1
|
|
command being
|
|
.Dl command_interpreter [...] command
|
|
so use that string to find the PID(s) of the running command
|
|
rather than
|
|
.Ql command .
|
|
.It Sy extra_commands
|
|
Extra commands/keywords/arguments supported.
|
|
.It Sy pidfile
|
|
Path to pid file.
|
|
Used to determine the PID(s) of the running command.
|
|
If
|
|
.Sy pidfile
|
|
is set, use
|
|
.Dl check_pidfile $pidfile $procname
|
|
to find the PID.
|
|
Otherwise, if
|
|
.Sy command
|
|
is set, use
|
|
.Dl check_process $procname
|
|
to find the PID.
|
|
.It Sy procname
|
|
Process name to check for.
|
|
Defaults to the value of
|
|
.Sy command .
|
|
.It Sy required_dirs
|
|
Check for the existence of the listed directories
|
|
before running the default start method.
|
|
.It Sy required_files
|
|
Check for the readability of the listed files
|
|
before running the default start method.
|
|
.It Sy required_vars
|
|
Perform
|
|
.Ic checkyesno
|
|
on each of the list variables
|
|
before running the default start method.
|
|
.It Sy ${name}_chdir
|
|
Directory to
|
|
.Ic cd
|
|
to before running
|
|
.Sy command ,
|
|
if
|
|
.Sy ${name}_chroot
|
|
is not provided.
|
|
.It Sy ${name}_chroot
|
|
Directory to
|
|
.Xr chroot 8
|
|
to before running
|
|
.Sy command .
|
|
Only supported after
|
|
.Pa /usr
|
|
is mounted.
|
|
.It Sy ${name}_env
|
|
List of additional or modified environment variables to set
|
|
when starting
|
|
.Sy command .
|
|
.It Sy ${name}_flags
|
|
Arguments to call
|
|
.Sy command
|
|
with.
|
|
This is usually set in
|
|
.Xr rc.conf 5 ,
|
|
and not in the
|
|
.Xr rc.d 8
|
|
script.
|
|
The environment variable
|
|
.Sq Ev flags
|
|
can be used to override this.
|
|
.It Sy ${name}_nice
|
|
.Xr nice 1
|
|
level to run
|
|
.Sy command
|
|
as.
|
|
Only supported after
|
|
.Pa /usr
|
|
is mounted.
|
|
.It Sy ${name}_user
|
|
User to run
|
|
.Sy command
|
|
as, using
|
|
.Xr chroot 8 .
|
|
if
|
|
.Sy ${name}_chroot
|
|
is set, otherwise
|
|
uses
|
|
.Xr su 1 .
|
|
Only supported after
|
|
.Pa /usr
|
|
is mounted.
|
|
.It Sy ${name}_group
|
|
Group to run the chrooted
|
|
.Sy command
|
|
as.
|
|
.It Sy ${name}_groups
|
|
Comma separated list of supplementary groups to run the chrooted
|
|
.Sy command
|
|
with.
|
|
.It Ar argument Ns Sy _cmd
|
|
Shell commands which override the default method for
|
|
.Ar argument .
|
|
.It Ar argument Ns Sy _precmd
|
|
Shell commands to run just before running
|
|
.Ar argument Ns Sy _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_*
|
|
checks and process (non-)existence checks.
|
|
.It Ar argument Ns Sy _postcmd
|
|
Shell commands to run if running
|
|
.Ar argument Ns Sy _cmd
|
|
or the default method for
|
|
.Ar argument
|
|
returned a zero exit code.
|
|
.It Sy sig_stop
|
|
Signal to send the processes to stop in the default
|
|
.Sy stop
|
|
method.
|
|
Defaults to
|
|
.Dv SIGTERM .
|
|
.It Sy sig_reload
|
|
Signal to send the processes to reload in the default
|
|
.Sy reload
|
|
method.
|
|
Defaults to
|
|
.Dv SIGHUP .
|
|
.El
|
|
.Pp
|
|
For a given method
|
|
.Ar argument ,
|
|
if
|
|
.Ar argument Ns Sy _cmd
|
|
is not defined, then a default method is provided by
|
|
.Sy run_rc_command :
|
|
.Bl -tag -width "argument" -offset indent
|
|
.It Sy Argument
|
|
.Sy Default method
|
|
.It Sy start
|
|
If
|
|
.Sy command
|
|
is not running and
|
|
.Ic checkyesno Sy rcvar
|
|
succeeds, start
|
|
.Sy command .
|
|
.It Sy stop
|
|
Determine the PIDs of
|
|
.Sy command
|
|
with
|
|
.Ic check_pidfile
|
|
or
|
|
.Ic check_process
|
|
(as appropriate),
|
|
.Ic kill Sy sig_stop
|
|
those PIDs, and run
|
|
.Ic wait_for_pids
|
|
on those PIDs.
|
|
.It Sy reload
|
|
Similar to
|
|
.Sy stop ,
|
|
except that it uses
|
|
.Sy sig_reload
|
|
instead, and doesn't run
|
|
.Ic wait_for_pids .
|
|
.It Sy restart
|
|
Runs the
|
|
.Sy stop
|
|
method, then the
|
|
.Sy start
|
|
method.
|
|
.It Sy status
|
|
Show the PID of
|
|
.Sy command ,
|
|
or some other script specific status operation.
|
|
.It Sy poll
|
|
Wait for
|
|
.Sy command
|
|
to exit.
|
|
.It Sy 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 .
|
|
.El
|
|
.Pp
|
|
The following variables are available to the methods
|
|
(such as
|
|
.Ar argument Ns Sy _cmd )
|
|
as well as after
|
|
.Ic run_rc_command
|
|
has completed:
|
|
.Bl -tag -width "rc_flags" -offset indent
|
|
.It Sy rc_arg
|
|
Argument provided to
|
|
.Sy run_rc_command ,
|
|
after fast and force processing has been performed.
|
|
.It Sy rc_flags
|
|
Flags to start the default command with.
|
|
Defaults to
|
|
.Sy ${name}_flags ,
|
|
unless overridden by the environment variable
|
|
.Sq Ev flags .
|
|
This variable may be changed by the
|
|
.Ar argument Ns Sy _precmd
|
|
method.
|
|
.It Sy rc_pid
|
|
PID of
|
|
.Sy command
|
|
(if appropriate).
|
|
.It Sy rc_fast
|
|
Not empty if
|
|
.Dq fast
|
|
prefix was used.
|
|
.It Sy rc_force
|
|
Not empty if
|
|
.Dq force
|
|
prefix was used.
|
|
.El
|
|
.It Ic run_rc_script Ar file Ar argument
|
|
Start the script
|
|
.Ar file
|
|
with an argument of
|
|
.Ar argument ,
|
|
and handle the return value from the script.
|
|
.Pp
|
|
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 .
|
|
.Ed
|
|
.Pp
|
|
The startup behaviour of
|
|
.Ar file
|
|
depends upon the following checks:
|
|
.Bl -enum
|
|
.It
|
|
If
|
|
.Ar file
|
|
ends in
|
|
.Pa .sh ,
|
|
it is sourced into the current shell.
|
|
.It
|
|
If
|
|
.Ar file
|
|
appears to be a backup or scratch file
|
|
(e.g., with a suffix of
|
|
.Sq ~ ,
|
|
.Sq # ,
|
|
.Sq .OLD ,
|
|
or
|
|
.Sq .orig ) ,
|
|
ignore it.
|
|
.It
|
|
If
|
|
.Ar file
|
|
is not executable, ignore it.
|
|
.It
|
|
If the
|
|
.Xr rc.conf 5
|
|
variable
|
|
.Sy rc_fast_and_loose
|
|
is empty,
|
|
source
|
|
.Ar file
|
|
in a sub shell,
|
|
otherwise source
|
|
.Ar file
|
|
into the current shell.
|
|
.It
|
|
If
|
|
.Ar file
|
|
contains the
|
|
.Xr rcorder 8
|
|
keyword
|
|
.Dq interactive ,
|
|
then the command is executed using
|
|
.Ic no_rc_postprocess .
|
|
.El
|
|
.It Ic stop_boot
|
|
Prevent booting to multiuser mode.
|
|
If the
|
|
.Sy autoboot
|
|
variable is
|
|
.Sq yes ,
|
|
then a
|
|
.Sy SIGTERM
|
|
signal is sent to the parent
|
|
process (which is assumed to be
|
|
.Xr rc 8 ) .
|
|
Otherwise, the shell exits with status
|
|
.Li 1 .
|
|
.It Ic twiddle
|
|
Display one of the characters
|
|
.Sq \&/ , \&- , \&\e , \&| ,
|
|
followed by a backspace.
|
|
Repeated calls to this function will create the appearance of a spinning
|
|
symbol, as a different character is displayed on each call.
|
|
Output is to
|
|
.Pa /dev/tty ,
|
|
so this function may be useful even inside a script whose output
|
|
has been redirected.
|
|
.It Ic wait_for_pids Op Ar pid Op Ar ...
|
|
Wait until all of the provided
|
|
.Ar pids
|
|
don't 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
|
|
and log it to the system log
|
|
using
|
|
.Xr logger 1 .
|
|
The warning message consists of the script name
|
|
(from
|
|
.Sy $0 ) ,
|
|
followed by
|
|
.Dq ": WARNING: " ,
|
|
and then
|
|
.Ar message .
|
|
.It Ic yesno_to_truefalse Ar var
|
|
Change the value of the specified variable from any of the
|
|
forms acceptable to the
|
|
.Ic checkyesno
|
|
function, to
|
|
.Dq true
|
|
or
|
|
.Dq false .
|
|
.El
|
|
.Sh FILES
|
|
.Bl -tag -width /etc/rc.subr -compact
|
|
.It Pa /etc/rc.subr
|
|
The
|
|
.Nm
|
|
file resides in
|
|
.Pa /etc .
|
|
.El
|
|
.Sh SEE ALSO
|
|
.Xr rc.conf 5 ,
|
|
.Xr rc 8
|
|
.Sh HISTORY
|
|
.Nm
|
|
appeared in
|
|
.Nx 1.3 .
|
|
The
|
|
.Xr rc.d 8
|
|
support functions appeared in
|
|
.Nx 1.5 .
|
|
Support for the
|
|
.Xr rc 8
|
|
post-processor appeared in
|
|
.Nx 6.0 .
|