rc.subr —
functions used by system shell scripts
rc.subr contains commonly used shell script functions
  which are used by various scripts such as
  rc(8), and the periodic system
  services which are controlled by
  daily.conf(5),
  monthly.conf(5),
  security.conf(5), and
  weekly.conf(5).
The rc.subr functions are accessed by
    sourcing /etc/rc.subr into the current shell.
The following shell functions are available:
  - backup_fileaction file
    current backup
- Make a backup copy of file into
      current. If the
      rc.conf(5) variable
      backup_uses_rcs is ‘YES’, use
      rcs(1) to archive the previous
      version of current, otherwise save the previous
      version of current as backup.
    action 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, and if necessary, the
          rcs(1) files are created as
          well.
- update
- file has changed and needs to be backed up. If
          current exists, it is copied to
          backup or checked into
          rcs(1) (if the repository
          file is old), and then file is copied to
          current.
- remove
- file is no longer being tracked by this backup
          mechanism. If rcs(1) is
          being used, an empty file is checked in and
          current is removed, otherwise
          current is moved to
          backup.
 basenamefile
      [suffix] Just like
      basename(1), except
      implemented using shell built-in commands, and usable before the
      /usr/bin direcory is available.
- checkyesnovar
- 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 that the warning message shown by this function when
        var is not set references a manual page where the
        user can find more information. Its name is picked up from the
        rcvar_manpage variable. 
- check_pidfilepidfile 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_processprocname [interpreter]
- Prints the PIDs of any processes that are running with a first argument
      that matches procname.
      interpreter is handled as per
      check_pidfile.
- collapse_backslash_newline
- Copy input to output, collapsing
      ⟨backslash⟩⟨newline⟩ to nothing, but leaving
      other backslashes alone. dirnamefile Just like
      dirname(1), except
      implemented using shell built-in commands, and usable before the
      /usr/bin direcory is available.
- errexitval message
- Display an error message to stderr, log it to the system
      log using logger(1), and
      exitwith an exit value of
      exitval. The error message consists of the script
      name (from $0), followed by “: ERROR: ”,
      and then message.
- load_rc_configcommand
- Source in the rc.conf(5)
      configuration files for command. First,
      /etc/rc.conf is sourced if it has not yet been
      read in. Then,
      /etc/rc.conf.d/command is
      sourced if it is an existing file. The latter may also contain other
      variable assignments to override run_rc_commandarguments defined by the calling script, to provide an easy mechanism for
      an administrator to override the behaviour of a given
      rc.d(8) script without
      requiring the editing of that script.
- load_rc_config_varcommand var
- Read the rc.conf(5)
      variable var for command and
      set in the current shell, using load_rc_configin
      a sub-shell to prevent unwanted side effects from other variable
      assignments.
- mount_critical_filesystemstype
- Go through a list of critical file systems, as found in the
      rc.conf(5) variable
      critical_filesystems_type,
      mounting each one that is not currently mounted.
- no_rc_postprocesscommand [arguments]
- Execute the specified command with the specified arguments, in such a way
      that its output bypasses the post-processor that
      rc(8) uses for most commands.
      This implies that the output will not appear in the
      /var/run/rc.log file, and will appear on the
      console regardless of the value of rc_silent. This
      is expected to be useful for interactive commands, and this mechanism is
      automatically used by run_rc_commandwhen a script
      contains the rcorder(8)
      keyword “interactive”.If invoked from a context that does not appear to be under the
        control of rc(8), then the
        command is executed without special treatment. 
- print_rc_metadatastring
- Print the specified string in such a way that it
      should be handled as meta-data by the
      rc(8) post-processor. If invoked
      from a context that does not appear to be under the control of
      rc(8), then the
      string is discarded.
    Any rc.d(8) script
        may invoke this function with an argument that begins with
        “note:”, followed by one line of arbitrary text; the text
        will be logged by rc(8) but
        will not be displayed on the console. The use of arguments that do not begin with
        “note:” is reserved for internal use by
        rc(8) and
        rc.subr.
 
- print_rc_normal[- -n] string
- Print the specified string in such a way that it
      should be handled as normal output by the
      rc(8) post-processor. If invoked
      from a context that does not appear to be under the control of
      rc(8), then the
      string is printed to standard output.
    If the -nflag is specified, then the
        string is printed without a newline.
 Intended use cases include: 
      - An rc.d script can use “print_rc_normal
          -n” to print a partial line in such a
          way that it appears immediately instead of being buffered by
          rc(8)'s post-processor.
- An rc.d script that is run via the no_rc_postprocess
          function (so most of its output is invisible to
          rc(8)'s post-processor) can
          use print_rc_normal to force some of its output to
          be seen by the post-processor.
 
- rc_usagecommand [...]
- Print a usage message for $0, with
      commands being the list of valid arguments prefixed
      by “[fast|force|one]”.
- reverse_listitem [...]
- Print the list of items in reverse order.
- run_rc_commandargument [parameter ...]
- Run the argument method for the current
      rc.d(8) script, based on the
      settings of various shell variables.
      run_rc_commandis extremely flexible, and allows
      fully functional 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.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). Also checks
          if the service is already running and refuses to start if it is. This
          latter check is not performed by standard
          NetBSD 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), stop the
          service. This should check that the service is running and complain if
          it's not.
- restart
- Perform a stop then a start.
          Defaults to displaying the process ID of the program (if
        running).
- rcvar
- Display which
          rc.conf(5) 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.
 
 run_rc_commanduses 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
          checkyesnoto determine if this method should
          be run.
- rcvar_manpage
- The manual page containing information about rcvar.
          It will be part of the warning message shown when
          rcvar is undefined. Defaults to
          rc.conf(5).
- command
- Full path to the command. Not required if
          argument_cmd is defined for
          each supported keyword.
- command_args
- Optional arguments and/or shell directives for
          command.
- command_interpreter
- command is started with
        #! command_interpreter
          [...]
 which results in its ps(1)
          command beingcommand_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, usecheck_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
          default start method.
- required_files
- Check for the readability of the listed files before running the
          default start method.
- required_vars
- Perform checkyesnoon each of the list
          variables before running the default start method.
- ${name}_chdir
- Directory to cdto before running
          command, if ${name}_chroot is not
          provided.
- ${name}_chroot
- Directory to chroot(8)
          to before running command. Only supported after
          /usr is mounted.
- ${name}_env
- List of additional or modified environment variables to set when
          starting command.
- ${name}_flags
- Arguments to call command with. This is usually set
          in rc.conf(5), and not
          in the rc.d(8) script. The
          environment variable ‘flags’ can
          be used to override this.
- ${name}_nice
- nice(1) level to run
          command as. Only supported after
          /usr is mounted.
- ${name}_user
- User to run command as, using
          chroot(8). if
          ${name}_chroot is set, otherwise uses
          su(1). 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.
- 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
- If command is not running and
          checkyesnorcvar succeeds,
          start command.
- stop
- Determine the PIDs of command with
          check_pidfileorcheck_process(as appropriate),killsig_stop those PIDs,
          and runwait_for_pidson those PIDs.
- reload
- Similar to stop, except that it uses
          sig_reload instead, and doesn't run
          wait_for_pids.
- restart
- Runs the stop method, then the
          start method.
- status
- Show the PID of command, or some other script
          specific status operation.
- poll
- Wait for command to exit.
- rcvar
- Display which
          rc.conf(5) variable is
          used (if any). This method always works, even if the appropriate
          rc.conf(5) variable is
          set to ‘NO’.
 
 The following variables are available to the methods (such as
        argument_cmd) as well as after
        run_rc_commandhas completed:
 
    
      - rc_arg
- Argument provided to run_rc_command, after fast and
          force processing has been performed.
- rc_flags
- Flags to start the default command with. Defaults to
          ${name}_flags, unless overridden by the environment
          variable ‘flags’. This variable
          may be changed by the
          argument_precmd method.
- rc_pid
- PID of command (if appropriate).
- rc_fast
- Not empty if “fast” prefix was used.
- rc_force
- Not empty if “force” prefix was used.
 
 
- run_rc_scriptfile 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. The startup behaviour of file depends
        upon the following checks: 
      - If file ends in .sh, it
          is sourced into the current shell.
- If file appears to be a backup or scratch file
          (e.g., with a suffix of ‘~’, ‘#’,
          ‘.OLD’, or ‘.orig’), ignore it.
- If file is not executable, ignore it.
- If the rc.conf(5)
          variable rc_fast_and_loose is empty, source
          file in a sub shell, otherwise source
          file into the current shell.
- If file contains the
          rcorder(8) keyword
          “interactive”, then the command is executed using
          no_rc_postprocess.
 
- stop_boot
- Prevent booting to multiuser mode. If the autoboot
      variable is ‘yes’, then a SIGTERM signal
      is sent to the parent process (which is assumed to be
      rc(8)). Otherwise, the shell
      exits with status 1.
- twiddle
- Display one of the characters ‘/, -, \, |’, 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 /dev/tty, so this function may be
      useful even inside a script whose output has been redirected.
- wait_for_pids[pid [...]]
- Wait until all of the provided pids don't exist any
      more, printing the list of outstanding pids every
      two seconds.
- warnmessage
- Display a warning message to stderr and log it to the
      system log using logger(1).
      The warning message consists of the script name (from
      $0), followed by “: WARNING: ”, and then
      message.
- yesno_to_truefalsevar
- Change the value of the specified variable from any of the forms
      acceptable to the checkyesnofunction, to
      “true” or “false”.
  - /etc/rc.subr
- The rc.subrfile resides in
      /etc.
rc.subr appeared in NetBSD 1.3.
  The rc.d(8) support functions
  appeared in NetBSD 1.5. Support for the
  rc(8) post-processor appeared in
  NetBSD 6.0.