--- name: "rc.subr" section: "8" platform: "freebsd" package: "base" version: "16.0-CURRENT-20261027-61c70dc16a79" release: "FreeBSD 16.0-CURRENT (2026-10-27)" platforms: ["freebsd", "openbsd"] url: "https://new.carta.tech/rc.subr" --- # rc.subr(8) functions used by system shell scripts ## NAME **rc.subr** – functions used by system shell scripts ## SYNOPSIS - **.** */etc/rc.subr* - **backup\_file** *action* *file* *current* *backup* - **checkyesno** *var* - **check\_pidfile** *pidfile* *procname* \[*interpreter*\] - **check\_process** *procname* \[*interpreter*\] - **DebugOn** *tag* *...* - **DebugOff** *tag* *...* - **debug** *message* - **dot** *file* *...* - **err** *exitval* *message* - **force\_depend** *name* - **info** *message* - **is\_verified** *file* - **load\_kld** \[**-e** *regex*\] \[**-m** *module*\] *file* - **load\_rc\_config** \[*flag*\] \[*service*\] - **load\_rc\_config\_var** *name* *var* - **mount\_critical\_filesystems** *type* - **rc\_log** *message* - **rc\_trace** *level* *message* - **rc\_usage** *command* *...* - **reverse\_list** *item* *...* - **run\_rc\_command** *argument* - **run\_rc\_script** *file* *argument* - **run\_rc\_scripts** \[options\] *file* *...* - **safe\_dot** *file* *...* - **sdot** *file* *...* - **startmsg** \[**-n**\] *message* - **vdot** *file* *...* - **wait\_for\_pids** \[*pid* *...*\] - **warn** *message* ## DESCRIPTION The **rc.subr** script contains commonly used shell script functions and variable definitions which are used by various scripts such as [rc(8)](/rc/8.md). Scripts required by ports in */usr/local/etc/rc.d* will also eventually be rewritten to make use of it. The **rc.subr** functions were mostly imported from NetBSD. They are accessed by sourcing */etc/rc.subr* into the current shell. The following shell functions are available: - **backup\_file** *action* *file* *current* *backup* Make a backup copy of *file* into *current*. Save the previous version of *current* as *backup*. The *action* argument may be one of the following: - **add** *file* is now being backed up by or possibly re-entered into this backup mechanism. *current* is created. - **update** *file* has changed and needs to be backed up. If *current* exists, it is copied to *backup* and then *file* is copied to *current*. - **remove** *file* is no longer being tracked by this backup mechanism. *current* is moved to *backup*. - **checkyesno** *var* Return 0 if *var* is defined to “YES”, “TRUE”, “ON”, or ‘1’. Return 1 if *var* is defined to “NO”, “FALSE”, “OFF”, or ‘0’. Otherwise, warn that *var* is not set correctly. The values are case insensitive. *Note*: *var* should be a variable name, not its value; **checkyesno** will expand the variable by itself. - **check\_pidfile** *pidfile* *procname* \[*interpreter*\] Parses the first word of the first line of *pidfile* for a PID, and ensures that the process with that PID is running and its first argument matches *procname*. Prints the matching PID if successful, otherwise nothing. If *interpreter* is provided, parse the first line of *procname*, ensure that the line is of the form: ``` #! interpreter [...] ``` and use *interpreter* with its optional arguments and *procname* appended as the process string to search for. - **check\_process** *procname* \[*interpreter*\] Prints the PIDs of any processes that are running with a first argument that matches *procname*. *interpreter* is handled as per **check\_pidfile**. - **DebugOn** *tag* *...* Enable tracing if not already enabled, and any *tag* is found in *DEBUG\_SH* (a comma separated list of tags). Record the *tag* that caused it to be enabled in *DEBUG\_ON*, set *DEBUG\_DO* empty and *DEBUG\_SKIP* to ‘:’. See [debug.sh(8)](/debug.sh/8.md) for more details. - **DebugOff** *tag* *...* Disable tracing if enabled and any *tag* matches *DEBUG\_ON*, which means it was the reason tracing was enabled. Set *DEBUG\_DO* to ‘:’, and *DEBUG\_ON*, *DEBUG\_SKIP* empty. - **debug** *message* Display a debugging message to *stderr*, log it to the system log using [logger(1)](/logger/1.md), and return to the caller. The error message consists of the script name (from *$0*), followed by “: DEBUG: ”, and then *message*. This function is intended to be used by developers as an aid to debugging scripts. It can be turned on or off by the [rc.conf(5)](/rc.conf/5.md) variable *rc\_debug*. - **dot** *file* *...* For reading in unverified files. Ensure shell verify option is off. This option is only meaningful when mac\_veriexec(4) is active. Read each *file* if it exists. Restore previous state of the verify option. - **err** *exitval* *message* Display an error message to *stderr*, log it to the system log using [logger(1)](/logger/1.md), and **exit** with an exit value of *exitval*. The error message consists of the script name (from *$0*), followed by “: ERROR: ”, and then *message*. - **force\_depend** *name* Output an advisory message and force the *name* service to start. The *name* argument is the [basename(1)](/basename/1.md) component of the path to the script located at */etc/rc.d* (scripts stored in other locations such as */usr/local/etc/rc.d* cannot be controlled with **force\_depend** currently). 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. - **is\_verified** *file* If veriexec(8) does not exist, or mac\_veriexec(4) is not active, just return success. Otherwise use veriexec(8) to check if *file* is verified. If not verified the return code will be 80 (EAUTH). - **info** *message* Display an informational message to *stdout*, and log it to the system log using [logger(1)](/logger/1.md). The message consists of the script name (from *$0*), followed by “: INFO: ”, and then *message*. The display of this informational output can be turned on or off by the [rc.conf(5)](/rc.conf/5.md) variable *rc\_info*. - **load\_kld** \[**-e** *regex*\] \[**-m** *module*\] *file* Load *file* as a kernel module unless it is already loaded. For the purpose of checking the module status, either the exact module name can be specified using **-m**, or an [egrep(1)](/egrep/1.md) regular expression matching the module name can be supplied via **-e**. By default, the module is assumed to have the same name as *file*, which is not always the case. - **load\_rc\_config** \[*flag*\] \[*service*\] Source in the configuration file(s) for *service*. If no *service* is specified, only the global configuration file(s) will be loaded. First, */etc/rc.conf* is sourced if it has not yet been read in. Then, */etc/rc.conf.d/**service* is sourced if it is an existing file. The latter may also contain other variable assignments to override **run\_rc\_command** arguments defined by the calling script, to provide an easy mechanism for an administrator to override the behaviour of a given [rc.d(8)](/rc.d/8.md) script without requiring the editing of that script. The function named by *load\_rc\_config\_reader* (default is **dot**) is used to read configuration unless *flag* is: - **-s** use **sdot** to read configuration, because we want verified configuration or to use **safe\_dot** to read an unverified configuration. - **-v** use **vdot** to read in configuration only if it is verified. **DebugOn** will be called with tags derived from *name* to enable tracing if any appear in *DEBUG\_SH*. - **load\_rc\_config\_var** *name* *var* Read the [rc.conf(5)](/rc.conf/5.md) variable *var* for *name* and set in the current shell, using **load\_rc\_config** in a sub-shell to prevent unwanted side effects from other variable assignments. - **mount\_critical\_filesystems** *type* Go through a list of critical file systems, as found in the [rc.conf(5)](/rc.conf/5.md) variable *critical\_filesystems\_**type*, mounting each one that is not currently mounted. - **rc\_log** *message* Output *message* with a timestamp, which is both human readable and easily parsed for post processing, using: ``` date "+@ %s [%Y-%m-%d %H:%M:%S %Z] $*" ``` - **rc\_trace** *level* *message* If the file */etc/rc.conf.d/rc\_trace* exists and is not empty attempt to set *RC\_LEVEL* based on its content. If the file is empty or does not contain a value for *RC\_LEVEL*, set it to 0. If *level* is greater than or equal to *RC\_LEVEL* pass *message* to **rc\_log**. - **rc\_usage** *command* *...* Print a usage message for *$0*, with *commands* being the list of valid arguments prefixed by “\[fast\|force\|one\|quiet\]”. - **reverse\_list** *item* *...* Print the list of *items* in reverse order. - **run\_rc\_command** *argument* Run the *argument* method for the current [rc.d(8)](/rc.d/8.md) script, based on the settings of various shell variables. **run\_rc\_command** is extremely flexible, and allows fully functional [rc.d(8)](/rc.d/8.md) scripts to be implemented in a small amount of shell code. *argument* is searched for in the list of supported commands, which may be one of: - **start** Start the service. This should check that the service is to be started as specified by [rc.conf(5)](/rc.conf/5.md). Also checks if the service is already running and refuses to start if it is. This latter check is not performed by standard FreeBSD scripts if the system is starting directly to multi-user mode, to speed up the boot process. - **stop** If the service is to be started as specified by [rc.conf(5)](/rc.conf/5.md), stop the service. This should check that the service is running and complain if it is not. - **restart** Perform a **stop** then a **start**. Defaults to displaying the process ID of the program (if running). - **enabled** Return 0 if the service is enabled and 1 if it is not. This command does not print anything. - **rcvar** Display which [rc.conf(5)](/rc.conf/5.md) variables are used to control the startup of the service (if any). If *pidfile* or *procname* is set, also support: - **poll** Wait for the command to exit. - **status** Show the status of the process. Other supported commands are listed in the optional variable *extra\_commands*. *argument* may have one of the following prefixes which alters its operation: - fast Skip the check for an existing running process, and sets *rc\_fast*=YES. - force Skip the checks for *rcvar* being set to “YES”, and sets *rc\_force*=YES. This ignores *argument**\_precmd* returning non-zero, and ignores any of the *required\_\** tests failing, and always returns a zero exit status. - one Skip the checks for *rcvar* being set to “YES”, but performs all the other prerequisite tests. - quiet Inhibits some verbose diagnostics. Currently, this includes messages "Starting ${name}" (as checked by **check\_startmsgs** inside **rc.subr**) and errors about usage of services that are not enabled in [rc.conf(5)](/rc.conf/5.md). This prefix also sets *rc\_quiet*=YES. *Note*: *rc\_quiet* is not intended to completely mask all debug and warning messages, but only certain small classes of them. **run\_rc\_command** uses the following shell variables to control its behaviour. Unless otherwise stated, these are optional. - *name* The name of this script. This is not optional. - *rcvar* The value of *rcvar* is checked with **checkyesno** to determine if this method should be run. - *command* Full path to the command. Not required if *argument**\_cmd* is defined for each supported keyword. Can be overridden by *${name}\_program*. - *command\_args* Optional arguments and/or shell directives for *command*. - *command\_interpreter* *command* is started with: ``` #! command_interpreter [...] ``` which results in its [ps(1)](/ps/1.md) command being: ``` command_interpreter [...] command ``` so use that string to find the PID(s) of the running command rather than *command*. - *extra\_commands* Extra commands/keywords/arguments supported. - *pidfile* Path to PID file. Used to determine the PID(s) of the running command. If *pidfile* is set, use: ``` check_pidfile $pidfile $procname ``` to find the PID. Otherwise, if *command* is set, use: ``` check_process $procname ``` to find the PID. - *procname* Process name to check for. Defaults to the value of *command*. - *required\_dirs* Check for the existence of the listed directories before running the **start** method. The list is checked before running *start\_precmd*. - *required\_files* Check for the readability of the listed files before running the **start** method. The list is checked before running *start\_precmd*. - *required\_modules* Ensure that the listed kernel modules are loaded before running the **start** method. The list is checked after running *start\_precmd*. This is done after invoking the commands from *start\_precmd* so that the missing modules are not loaded in vain if the preliminary commands indicate a error condition. A word in the list can have an optional “:*modname*” or “~*pattern*” suffix. The *modname* or *pattern* parameter is passed to **load\_kld** through a **-m** or **-e** option, respectively. See the description of **load\_kld** in this document for details. - *required\_vars* Perform **checkyesno** on each of the list variables before running the **start** method. The list is checked after running *start\_precmd*. - *${name}\_chdir* Directory to **cd** to before running *command*, if *${name}\_chroot* is not provided. - *${name}\_chroot* Directory to [chroot(8)](/chroot/8.md) to before running *command*. Only supported after */usr* is mounted. - *${name}\_env* A list of environment variables to run *command* with. Those variables will be passed as arguments to the [env(1)](/env/1.md) utility unless *argument**\_cmd* is defined. In that case the contents of *${name}\_env* will be exported via the [export(1)](/export/1.md) builtin of [sh(1)](/sh/1.md), which puts some limitations on the names of variables (e.g., a variable name may not start with a digit). - *${name}\_env\_file* A file to source for environmental variables to run *command* with. *Note*: all the variables which are being assigned in this file are going to be exported into the environment of *command*. - *${name}\_fib* FIB *Routing* *Table* number to run *command* with. See [setfib(1)](/setfib/1.md) for more details. - *${name}\_flags* Arguments to call *command* with. This is usually set in [rc.conf(5)](/rc.conf/5.md), and not in the [rc.d(8)](/rc.d/8.md) script. The environment variable ‘flags’ can be used to override this. - *${name}\_nice* [nice(1)](/nice/1.md) level to run *command* as. Only supported after */usr* is mounted. - *${name}\_limits* Resource limits to apply to *command*. This will be passed as arguments to the [limits(1)](/limits/1.md) utility. By default, the resource limits are based on the login class defined in *${name}\_login\_class*. - *${name}\_login\_class* Login class to use with *${name}\_limits*. Defaults to “daemon”. - *${name}\_offcmd* Shell commands to run during start if a service is not enabled. - *${name}\_oomprotect* [protect(1)](/protect/1.md) *command* from being killed when swap space is exhausted. If “YES” is used, no child processes are protected. If “ALL”, protect all child processes. - *${name}\_program* Full path to the command. Overrides *command* if both are set, but has no effect if *command* is unset. As a rule, *command* should be set in the script while *${name}\_program* should be set in [rc.conf(5)](/rc.conf/5.md). - *${name}\_user* User to run *command* as, using [chroot(8)](/chroot/8.md) if *${name}\_chroot* is set, otherwise uses [su(1)](/su/1.md). Only supported after */usr* is mounted. - *${name}\_group* Group to run the chrooted *command* as. - *${name}\_groups* Comma separated list of supplementary groups to run the chrooted *command* with. - *${name}\_prepend* Commands to be prepended to *command*. This is a generic version of *${name}\_env*, *${name}\_fib*, or *${name}\_nice*. - *${name}\_setup* Optional command to be run during **start**, **restart**, and **reload** prior to the respective *argument**\_precmd*. If the command fails for any reason it will output a warning, but execution will continue. - *argument**\_cmd* Shell commands which override the default method for *argument*. - *argument**\_precmd* Shell commands to run just before running *argument**\_cmd* or the default method for *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 *required\_\** checks and process (non-)existence checks. - *argument**\_postcmd* Shell commands to run if running *argument**\_cmd* or the default method for *argument* returned a zero exit code. - *sig\_stop* Signal to send the processes to stop in the default **stop** method. Defaults to SIGTERM. - *sig\_reload* Signal to send the processes to reload in the default **reload** method. Defaults to SIGHUP. For a given method *argument*, if *argument**\_cmd* is not defined, then a default method is provided by **run\_rc\_command**: | | | | --- | --- | | **Argument** | **Default** **method** | | **start** | | | **stop** | | | **reload** | | | **restart** | | | **status** | | | **poll** | | | **rcvar** | | - **run\_rc\_script** *file* *argument* Start the script *file* with an argument of *argument*, and handle the return value from the script. Various shell variables are unset before *file* is started: *name*, *command*, *command\_args*, *command\_interpreter*, *extra\_commands*, *pidfile*, *rcvar*, *required\_dirs*, *required\_files*, *required\_vars*, *argument**\_cmd*, *argument**\_precmd*. *argument**\_postcmd*. Call **rc\_trace** to indicate that *file* is to be run. However, if **is\_verified** *file* fails, just return. **DebugOn** will be called with tags derived from *name* and *rc\_arg* to enable tracing if any of those tags appear in *DEBUG\_SH*. **run\_rc\_script** executes *file* unless: 1. *file* ends in *.sh* and lives in */etc/rc.d*. 2. *file* appears to be a backup or scratch file (e.g., with a suffix of *~*, *#*, *.OLD*, *,v*, or *.orig*). 3. *file* is not executable. - **run\_rc\_scripts** \[options\] file ... Call **run\_rc\_script** for each *file*, unless it is already recorded as having been run. The *options* are: - **--arg** *arg* Pass *arg* to **run\_rc\_script**, default is *\_boot* set by [rc(8)](/rc/8.md). - **--break** *break* Stop processing if any *file* matches any *break* - **safe\_dot** *file* *...* Used by **sdot** when mac\_veriexec(4) is active and *file* is not verified. This function limits the input from *file* to simple variable assignments with any non-alphanumeric characters replaced with ‘\_’. - **sdot** *file* *...* For reading in configuration files. Skip files that do not exist or are empty. Try using **vdot** and if that fails (the file is unverified) fall back to using **safe\_dot**. - **startmsg** \[**-n**\] *message* Display a start message to *stdout*. It should be used instead of [echo(1)](/echo/1.md). The display of this output can be turned off if the [rc.conf(5)](/rc.conf/5.md) variable *rc\_startmsgs* is set to “NO”. - **stop\_boot** \[*always*\] Prevent booting to multiuser mode. If the *autoboot* variable is set to ‘yes’ (see [rc(8)](/rc/8.md) to learn more about *autoboot*), or **checkyesno** *always* indicates a truth value, then a SIGTERM signal is sent to the parent process, which is assumed to be [rc(8)](/rc/8.md). Otherwise, the shell exits with a non-zero status. - **vdot** *file* *...* For reading in only verified files. Ensure shell verify option is on. This option is only meaningful when mac\_veriexec(4) is active, otherwise this function is effectively the same as **dot**. Read in each *file* if it exists and **is\_verfied** *file* is successful, otherwise set return code to 80 (EAUTH). Restore previous state of the verify option. - **wait\_for\_pids** \[*pid* *...*\] Wait until all of the provided *pids* do not exist any more, printing the list of outstanding *pids* every two seconds. - **warn** *message* Display a warning message to *stderr* and log it to the system log using [logger(1)](/logger/1.md). The warning message consists of the script name (from *$0*), followed by “: WARNING: ”, and then *message*. ## FILES - */etc/rc.subr* The **rc.subr** file resides in */etc*. ## SEE ALSO [rc.conf(5)](/rc.conf/5.md), [debug.sh(8)](/debug.sh/8.md), [rc(8)](/rc/8.md) ## HISTORY The **rc.subr** script appeared in NetBSD 1.3. The [rc.d(8)](/rc.d/8.md) support functions appeared in NetBSD 1.5. The **rc.subr** script first appeared in FreeBSD 5.0.