share/man/man8/rc.subr.8

   1 .\"     $NetBSD: rc.subr.8,v 1.12 2004/01/06 00:52:24 lukem Exp $
   2 .\"
   3 .\" Copyright (c) 2002-2004 The NetBSD Foundation, Inc.
   4 .\" All rights reserved.
   5 .\"
   6 .\" This code is derived from software contributed to The NetBSD Foundation
   7 .\" by Luke Mewburn.
   8 .\"
   9 .\" Redistribution and use in source and binary forms, with or without
  10 .\" modification, are permitted provided that the following conditions
  11 .\" are met:
  12 .\" 1. Redistributions of source code must retain the above copyright
  13 .\"    notice, this list of conditions and the following disclaimer.
  14 .\" 2. Redistributions in binary form must reproduce the above copyright
  15 .\"    notice, this list of conditions and the following disclaimer in the
  16 .\"    documentation and/or other materials provided with the distribution.
  17 .\"
  18 .\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
  19 .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
  20 .\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
  21 .\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
  22 .\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
  23 .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
  24 .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
  25 .\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
  26 .\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
  27 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
  28 .\" POSSIBILITY OF SUCH DAMAGE.
  29 .\"
  30 .\" $FreeBSD$
  31 .\"
  32 .Dd February 4, 2016
  33 .Dt RC.SUBR 8
  34 .Os
  35 .Sh NAME
  36 .Nm rc.subr
  37 .Nd functions used by system shell scripts
  38 .Sh SYNOPSIS
  39 .Bl -item -compact
  40 .It
  41 .Ic .\& Pa /etc/rc.subr
  42 .Pp
  43 .It
  44 .Ic backup_file Ar action Ar file Ar current Ar backup
  45 .It
  46 .Ic checkyesno Ar var
  47 .It
  48 .Ic check_pidfile Ar pidfile Ar procname Op Ar interpreter
  49 .It
  50 .Ic check_process Ar procname Op Ar interpreter
  51 .It
  52 .Ic debug Ar message
  53 .It
  54 .Ic err Ar exitval Ar message
  55 .It
  56 .Ic force_depend Ar name
  57 .It
  58 .Ic info Ar message
  59 .It
  60 .Ic load_kld Oo Fl e Ar regex Oc Oo Fl m Ar module Oc Ar file
  61 .It
  62 .Ic load_rc_config Ar name
  63 .It
  64 .Ic load_rc_config_var Ar name Ar var
  65 .It
  66 .Ic mount_critical_filesystems Ar type
  67 .It
  68 .Ic rc_usage Ar command ...
  69 .It
  70 .Ic reverse_list Ar item ...
  71 .It
  72 .Ic run_rc_command Ar argument
  73 .It
  74 .Ic run_rc_script Ar file Ar argument
  75 .It
  76 .Ic wait_for_pids Op Ar pid ...
  77 .It
  78 .Ic warn Ar message
  79 .El
  80 .Sh DESCRIPTION
  81 The
  82 .Nm
  83 script
  84 contains commonly used shell script functions and variable
  85 definitions which are used by various scripts such as
  86 .Xr rc 8 .
  87 Scripts required by ports in
  88 .Pa /usr/local/etc/rc.d
  89 will also eventually
  90 be rewritten to make use of it.
  91 .Pp
  92 The
  93 .Nm
  94 functions were mostly imported from
  95 .Nx .
  96 .Pp
  97 They are accessed by sourcing
  98 .Pa /etc/rc.subr
  99 into the current shell.
 100 .Pp
 101 The following shell functions are available:
 102 .Bl -tag -width 4n
 103 .It Ic backup_file Ar action file current backup
 104 Make a backup copy of
 105 .Ar file
 106 into
 107 .Ar current .
 108 If the
 109 .Xr rc.conf 5
 110 variable
 111 .Va backup_uses_rcs
 112 is
 113 .Dq Li YES ,
 114 use
 115 .Xr rcs 1
 116 to archive the previous version of
 117 .Ar current ,
 118 otherwise save the previous version of
 119 .Ar current
 120 as
 121 .Ar backup .
 122 .Pp
 123 The
 124 .Ar action
 125 argument
 126 may be one of the following:
 127 .Bl -tag -width ".Cm remove"
 128 .It Cm add
 129 .Ar file
 130 is now being backed up by or possibly re-entered into this backup mechanism.
 131 .Ar current
 132 is created, and if necessary, the
 133 .Xr rcs 1
 134 files are created as well.
 135 .It Cm update
 136 .Ar file
 137 has changed and needs to be backed up.
 138 If
 139 .Ar current
 140 exists, it is copied to
 141 .Ar backup
 142 or checked into
 143 .Xr rcs 1
 144 (if the repository file is old),
 145 and then
 146 .Ar file
 147 is copied to
 148 .Ar current .
 149 .It Cm remove
 150 .Ar file
 151 is no longer being tracked by this backup mechanism.
 152 If
 153 .Xr rcs 1
 154 is being used, an empty file is checked in and
 155 .Ar current
 156 is removed,
 157 otherwise
 158 .Ar current
 159 is moved to
 160 .Ar backup .
 161 .El
 162 .It Ic checkyesno Ar var
 163 Return 0 if
 164 .Ar var
 165 is defined to
 166 .Dq Li YES ,
 167 .Dq Li TRUE ,
 168 .Dq Li ON ,
 169 or
 170 .Ql 1 .
 171 Return 1 if
 172 .Ar var
 173 is defined to
 174 .Dq Li NO ,
 175 .Dq Li FALSE ,
 176 .Dq Li OFF ,
 177 or
 178 .Ql 0 .
 179 Otherwise, warn that
 180 .Ar var
 181 is not set correctly.
 182 The values are case insensitive.
 183 .Sy Note :
 184 .Ar var
 185 should be a variable name, not its value;
 186 .Ic checkyesno
 187 will expand the variable by itself.
 188 .It Ic check_pidfile Ar pidfile procname Op Ar interpreter
 189 Parses the first word of the first line of
 190 .Ar pidfile
 191 for a PID, and ensures that the process with that PID
 192 is running and its first argument matches
 193 .Ar procname .
 194 Prints the matching PID if successful, otherwise nothing.
 195 If
 196 .Ar interpreter
 197 is provided, parse the first line of
 198 .Ar procname ,
 199 ensure that the line is of the form:
 200 .Pp
 201 .Dl "#! interpreter [...]"
 202 .Pp
 203 and use
 204 .Ar interpreter
 205 with its optional arguments and
 206 .Ar procname
 207 appended as the process string to search for.
 208 .It Ic check_process Ar procname Op Ar interpreter
 209 Prints the PIDs of any processes that are running with a first
 210 argument that matches
 211 .Ar procname .
 212 .Ar interpreter
 213 is handled as per
 214 .Ic check_pidfile .
 215 .It Ic debug Ar message
 216 Display a debugging message to
 217 .Va stderr ,
 218 log it to the system log using
 219 .Xr logger 1 ,
 220 and
 221 return to the caller.
 222 The error message consists of the script name
 223 (from
 224 .Va $0 ) ,
 225 followed by
 226 .Dq Li ": DEBUG: " ,
 227 and then
 228 .Ar message .
 229 This function is intended to be used by developers
 230 as an aid to debugging scripts.
 231 It can be turned on or off
 232 by the
 233 .Xr rc.conf 5
 234 variable
 235 .Va rc_debug .
 236 .It Ic err Ar exitval message
 237 Display an error message to
 238 .Va stderr ,
 239 log it to the system log
 240 using
 241 .Xr logger 1 ,
 242 and
 243 .Ic exit
 244 with an exit value of
 245 .Ar exitval .
 246 The error message consists of the script name
 247 (from
 248 .Va $0 ) ,
 249 followed by
 250 .Dq Li ": ERROR: " ,
 251 and then
 252 .Ar message .
 253 .It Ic force_depend Ar name
 254 Output an advisory message and force the
 255 .Ar name
 256 service to start.
 257 The
 258 .Ar name
 259 argument is the
 260 .Xr basename 1
 261 component of the path to the script, usually
 262 .Pa /etc/rc.d/name .
 263 If the script fails for any reason it will output a warning
 264 and return with a return value of 1.
 265 If it was successful
 266 it will return 0.
 267 .It Ic info Ar message
 268 Display an informational message to
 269 .Va stdout ,
 270 and log it to the system log using
 271 .Xr logger 1 .
 272 The message consists of the script name
 273 (from
 274 .Va $0 ) ,
 275 followed by
 276 .Dq Li ": INFO: " ,
 277 and then
 278 .Ar message .
 279 The display of this informational output can be
 280 turned on or off by the
 281 .Xr rc.conf 5
 282 variable
 283 .Va rc_info .
 284 .It Ic load_kld Oo Fl e Ar regex Oc Oo Fl m Ar module Oc Ar file
 285 Load
 286 .Ar file
 287 as a kernel module unless it is already loaded.
 288 For the purpose of checking the module status,
 289 either the exact module name can be specified using
 290 .Fl m ,
 291 or an
 292 .Xr egrep 1
 293 regular expression matching the module name can be supplied via
 294 .Fl e .
 295 By default, the module is assumed to have the same name as
 296 .Ar file ,
 297 which is not always the case.
 298 .It Ic load_rc_config Ar name
 299 Source in the configuration files for
 300 .Ar name .
 301 First,
 302 .Pa /etc/rc.conf
 303 is sourced if it has not yet been read in.
 304 Then,
 305 .Pa /etc/rc.conf.d/ Ns Ar name
 306 is sourced if it is an existing file.
 307 The latter may also contain other variable assignments to override
 308 .Ic run_rc_command
 309 arguments defined by the calling script, to provide an easy
 310 mechanism for an administrator to override the behaviour of a given
 311 .Xr rc.d 8
 312 script without requiring the editing of that script.
 313 .It Ic load_rc_config_var Ar name Ar var
 314 Read the
 315 .Xr rc.conf 5
 316 variable
 317 .Ar var
 318 for
 319 .Ar name
 320 and set in the current shell, using
 321 .Ic load_rc_config
 322 in a sub-shell to prevent unwanted side effects from other variable
 323 assignments.
 324 .It Ic mount_critical_filesystems Ar type
 325 Go through a list of critical file systems,
 326 as found in the
 327 .Xr rc.conf 5
 328 variable
 329 .Va critical_filesystems_ Ns Ar type ,
 330 mounting each one that
 331 is not currently mounted.
 332 .It Ic rc_usage Ar command ...
 333 Print a usage message for
 334 .Va $0 ,
 335 with
 336 .Ar commands
 337 being the list of valid arguments
 338 prefixed by
 339 .Sm off
 340 .Dq Bq Li fast | force | one | quiet .
 341 .Sm on
 342 .It Ic reverse_list Ar item ...
 343 Print the list of
 344 .Ar items
 345 in reverse order.
 346 .It Ic run_rc_command Ar argument
 347 Run the
 348 .Ar argument
 349 method for the current
 350 .Xr rc.d 8
 351 script, based on the settings of various shell variables.
 352 .Ic run_rc_command
 353 is extremely flexible, and allows fully functional
 354 .Xr rc.d 8
 355 scripts to be implemented in a small amount of shell code.
 356 .Pp
 357 .Ar argument
 358 is searched for in the list of supported commands, which may be one
 359 of:
 360 .Bl -tag -width ".Cm restart" -offset indent
 361 .It Cm start
 362 Start the service.
 363 This should check that the service is to be started as specified by
 364 .Xr rc.conf 5 .
 365 Also checks if the service is already running and refuses to start if
 366 it is.
 367 This latter check is not performed by standard
 368 .Fx
 369 scripts if the system is starting directly to multi-user mode, to
 370 speed up the boot process.
 371 .It Cm stop
 372 If the service is to be started as specified by
 373 .Xr rc.conf 5 ,
 374 stop the service.
 375 This should check that the service is running and complain if it is not.
 376 .It Cm restart
 377 Perform a
 378 .Cm stop
 379 then a
 380 .Cm start .
 381 Defaults to displaying the process ID of the program (if running).
 382 .It Cm enabled
 383 Return 0 if the service is enabled and 1 if it is not.
 384 This command does not print anything.
 385 .It Cm rcvar
 386 Display which
 387 .Xr rc.conf 5
 388 variables are used to control the startup of the service (if any).
 389 .El
 390 .Pp
 391 If
 392 .Va pidfile
 393 or
 394 .Va procname
 395 is set, also support:
 396 .Bl -tag -width ".Cm restart" -offset indent
 397 .It Cm poll
 398 Wait for the command to exit.
 399 .It Cm status
 400 Show the status of the process.
 401 .El
 402 .Pp
 403 Other supported commands are listed in the optional variable
 404 .Va extra_commands .
 405 .Pp
 406 .Ar argument
 407 may have one of the following prefixes which alters its operation:
 408 .Bl -tag -width ".Li force" -offset indent
 409 .It Li fast
 410 Skip the check for an existing running process,
 411 and sets
 412 .Va rc_fast Ns = Ns Li YES .
 413 .It Li force
 414 Skip the checks for
 415 .Va rcvar
 416 being set to
 417 .Dq Li YES ,
 418 and sets
 419 .Va rc_force Ns = Ns Li YES .
 420 This ignores
 421 .Ar argument Ns Va _precmd
 422 returning non-zero, and ignores any of the
 423 .Va required_*
 424 tests failing, and always returns a zero exit status.
 425 .It Li one
 426 Skip the checks for
 427 .Va rcvar
 428 being set to
 429 .Dq Li YES ,
 430 but performs all the other prerequisite tests.
 431 .It Li quiet
 432 Inhibits some verbose diagnostics.
 433 Currently, this includes messages
 434 .Qq Starting ${name}
 435 (as checked by
 436 .Ic check_startmsgs
 437 inside
 438 .Nm )
 439 and errors about usage of services that are not enabled in
 440 .Xr rc.conf 5 .
 441 This prefix also sets
 442 .Va rc_quiet Ns = Ns Li YES .
 443 .Em Please, note:
 444 .Va rc_quiet
 445 is not intended to completely mask all debug and warning messages,
 446 but only certain small classes of them.
 447 .El
 448 .Pp
 449 .Ic run_rc_command
 450 uses the following shell variables to control its behaviour.
 451 Unless otherwise stated, these are optional.
 452 .Bl -tag -width ".Va procname" -offset indent
 453 .It Va name
 454 The name of this script.
 455 This is not optional.
 456 .It Va rcvar
 457 The value of
 458 .Va rcvar
 459 is checked with
 460 .Ic checkyesno
 461 to determine if this method should be run.
 462 .It Va command
 463 Full path to the command.
 464 Not required if
 465 .Ar argument Ns Va _cmd
 466 is defined for each supported keyword.
 467 Can be overridden by
 468 .Va ${name}_program .
 469 .It Va command_args
 470 Optional arguments and/or shell directives for
 471 .Va command .
 472 .It Va command_interpreter
 473 .Va command
 474 is started with:
 475 .Pp
 476 .Dl "#! command_interpreter [...]"
 477 .Pp
 478 which results in its
 479 .Xr ps 1
 480 command being:
 481 .Pp
 482 .Dl "command_interpreter [...] command"
 483 .Pp
 484 so use that string to find the PID(s) of the running command
 485 rather than
 486 .Va command .
 487 .It Va extra_commands
 488 Extra commands/keywords/arguments supported.
 489 .It Va pidfile
 490 Path to PID file.
 491 Used to determine the PID(s) of the running command.
 492 If
 493 .Va pidfile
 494 is set, use:
 495 .Pp
 496 .Dl "check_pidfile $pidfile $procname"
 497 .Pp
 498 to find the PID.
 499 Otherwise, if
 500 .Va command
 501 is set, use:
 502 .Pp
 503 .Dl "check_process $procname"
 504 .Pp
 505 to find the PID.
 506 .It Va procname
 507 Process name to check for.
 508 Defaults to the value of
 509 .Va command .
 510 .It Va required_dirs
 511 Check for the existence of the listed directories
 512 before running the
 513 .Cm start
 514 method.
 515 .It Va required_files
 516 Check for the readability of the listed files
 517 before running the
 518 .Cm start
 519 method.
 520 .It Va required_modules
 521 Ensure that the listed kernel modules are loaded
 522 before running the
 523 .Cm start
 524 method.
 525 This is done after invoking the commands from
 526 .Va start_precmd
 527 so that the missing modules are not loaded in vain
 528 if the preliminary commands indicate a error condition.
 529 A word in the list can have an optional
 530 .Dq Li : Ns Ar modname
 531 or
 532 .Dq Li ~ Ns Ar pattern
 533 suffix.
 534 The
 535 .Ar modname
 536 or
 537 .Ar pattern
 538 parameter is passed to
 539 .Ic load_kld
 540 through a
 541 .Fl m
 542 or
 543 .Fl e
 544 option, respectively.
 545 See the description of
 546 .Ic load_kld
 547 in this document for details.
 548 .It Va required_vars
 549 Perform
 550 .Ic checkyesno
 551 on each of the list variables
 552 before running the
 553 .Cm start
 554 method.
 555 .It Va ${name}_chdir
 556 Directory to
 557 .Ic cd
 558 to before running
 559 .Va command ,
 560 if
 561 .Va ${name}_chroot
 562 is not provided.
 563 .It Va ${name}_chroot
 564 Directory to
 565 .Xr chroot 8
 566 to before running
 567 .Va command .
 568 Only supported after
 569 .Pa /usr
 570 is mounted.
 571 .It Va ${name}_env
 572 A list of environment variables to run
 573 .Va command
 574 with.
 575 This will be passed as arguments to
 576 .Xr env 1
 577 utility.
 578 .It Va ${name}_fib
 579 FIB
 580 .Pa Routing Table
 581 number to run
 582 .Va command
 583 with.
 584 See
 585 .Xr setfib 1
 586 for more details.
 587 .It Va ${name}_flags
 588 Arguments to call
 589 .Va command
 590 with.
 591 This is usually set in
 592 .Xr rc.conf 5 ,
 593 and not in the
 594 .Xr rc.d 8
 595 script.
 596 The environment variable
 597 .Sq Ev flags
 598 can be used to override this.
 599 .It Va ${name}_nice
 600 .Xr nice 1
 601 level to run
 602 .Va command
 603 as.
 604 Only supported after
 605 .Pa /usr
 606 is mounted.
 607 .It Va ${name}_oomprotect
 608 .Xr protect 1
 609 .Va command
 610 from being killed when swap space is exhausted.
 611 If
 612 .Em YES
 613 is used, no child processes are protected.
 614 If
 615 .Em ALL ,
 616 protect all child processes.
 617 .It Va ${name}_program
 618 Full path to the command.
 619 Overrides
 620 .Va command
 621 if both are set, but has no effect if
 622 .Va command
 623 is unset.
 624 As a rule,
 625 .Va command
 626 should be set in the script while
 627 .Va ${name}_program
 628 should be set in
 629 .Xr rc.conf 5 .
 630 .It Va ${name}_user
 631 User to run
 632 .Va command
 633 as, using
 634 .Xr chroot 8
 635 if
 636 .Va ${name}_chroot
 637 is set, otherwise
 638 uses
 639 .Xr su 1 .
 640 Only supported after
 641 .Pa /usr
 642 is mounted.
 643 .It Va ${name}_group
 644 Group to run the chrooted
 645 .Va command
 646 as.
 647 .It Va ${name}_groups
 648 Comma separated list of supplementary groups to run the chrooted
 649 .Va command
 650 with.
 651 .It Va ${name}_prepend
 652 Commands to be prepended to
 653 .Va command .
 654 This is a generic version of
 655 .Va ${name}_env ,
 656 .Va ${name}_fib ,
 657 or
 658 .Va ${name}_nice .
 659 .It Ar argument Ns Va _cmd
 660 Shell commands which override the default method for
 661 .Ar argument .
 662 .It Ar argument Ns Va _precmd
 663 Shell commands to run just before running
 664 .Ar argument Ns Va _cmd
 665 or the default method for
 666 .Ar argument .
 667 If this returns a non-zero exit code, the main method is not performed.
 668 If the default method is being executed, this check is performed after
 669 the
 670 .Va required_*
 671 checks and process (non-)existence checks.
 672 .It Ar argument Ns Va _postcmd
 673 Shell commands to run if running
 674 .Ar argument Ns Va _cmd
 675 or the default method for
 676 .Ar argument
 677 returned a zero exit code.
 678 .It Va sig_stop
 679 Signal to send the processes to stop in the default
 680 .Cm stop
 681 method.
 682 Defaults to
 683 .Dv SIGTERM .
 684 .It Va sig_reload
 685 Signal to send the processes to reload in the default
 686 .Cm reload
 687 method.
 688 Defaults to
 689 .Dv SIGHUP .
 690 .El
 691 .Pp
 692 For a given method
 693 .Ar argument ,
 694 if
 695 .Ar argument Ns Va _cmd
 696 is not defined, then a default method is provided by
 697 .Ic run_rc_command :
 698 .Bl -tag -width ".Sy Argument" -offset indent
 699 .It Sy Argument
 700 .Sy Default method
 701 .It Cm start
 702 If
 703 .Va command
 704 is not running and
 705 .Ic checkyesno Va rcvar
 706 succeeds, start
 707 .Va command .
 708 .It Cm stop
 709 Determine the PIDs of
 710 .Va command
 711 with
 712 .Ic check_pidfile
 713 or
 714 .Ic check_process
 715 (as appropriate),
 716 .Ic kill Va sig_stop
 717 those PIDs, and run
 718 .Ic wait_for_pids
 719 on those PIDs.
 720 .It Cm reload
 721 Similar to
 722 .Cm stop ,
 723 except that it uses
 724 .Va sig_reload
 725 instead, and does not run
 726 .Ic wait_for_pids .
 727 Another difference from
 728 .Cm stop
 729 is that
 730 .Cm reload
 731 is not provided by default.
 732 It can be enabled via
 733 .Va extra_commands
 734 if appropriate:
 735 .Pp
 736 .Dl "extra_commands=reload"
 737 .It Cm restart
 738 Runs the
 739 .Cm stop
 740 method, then the
 741 .Cm start
 742 method.
 743 .It Cm status
 744 Show the PID of
 745 .Va command ,
 746 or some other script specific status operation.
 747 .It Cm poll
 748 Wait for
 749 .Va command
 750 to exit.
 751 .It Cm rcvar
 752 Display which
 753 .Xr rc.conf 5
 754 variable is used (if any).
 755 This method always works, even if the appropriate
 756 .Xr rc.conf 5
 757 variable is set to
 758 .Dq Li NO .
 759 .El
 760 .Pp
 761 The following variables are available to the methods
 762 (such as
 763 .Ar argument Ns Va _cmd )
 764 as well as after
 765 .Ic run_rc_command
 766 has completed:
 767 .Bl -tag -width ".Va rc_flags" -offset indent
 768 .It Va rc_arg
 769 Argument provided to
 770 .Ic run_rc_command ,
 771 after fast and force processing has been performed.
 772 .It Va rc_flags
 773 Flags to start the default command with.
 774 Defaults to
 775 .Va ${name}_flags ,
 776 unless overridden by the environment variable
 777 .Sq Ev flags .
 778 This variable may be changed by the
 779 .Ar argument Ns Va _precmd
 780 method.
 781 .It Va rc_pid
 782 PID of
 783 .Va command
 784 (if appropriate).
 785 .It Va rc_fast
 786 Not empty if
 787 .Dq Li fast
 788 prefix was used.
 789 .It Va rc_force
 790 Not empty if
 791 .Dq Li force
 792 prefix was used.
 793 .El
 794 .It Ic run_rc_script Ar file argument
 795 Start the script
 796 .Ar file
 797 with an argument of
 798 .Ar argument ,
 799 and handle the return value from the script.
 800 .Pp
 801 Various shell variables are unset before
 802 .Ar file
 803 is started:
 804 .Bd -ragged -offset indent
 805 .Va name ,
 806 .Va command ,
 807 .Va command_args ,
 808 .Va command_interpreter ,
 809 .Va extra_commands ,
 810 .Va pidfile ,
 811 .Va rcvar ,
 812 .Va required_dirs ,
 813 .Va required_files ,
 814 .Va required_vars ,
 815 .Ar argument Ns Va _cmd ,
 816 .Ar argument Ns Va _precmd .
 817 .Ar argument Ns Va _postcmd .
 818 .Ed
 819 .Pp
 820 The startup behaviour of
 821 .Ar file
 822 depends upon the following checks:
 823 .Bl -enum
 824 .It
 825 If
 826 .Ar file
 827 ends in
 828 .Pa .sh ,
 829 it is sourced into the current shell.
 830 .It
 831 If
 832 .Ar file
 833 appears to be a backup or scratch file
 834 (e.g., with a suffix of
 835 .Pa ~ , # , .OLD ,
 836 or
 837 .Pa .orig ) ,
 838 ignore it.
 839 .It
 840 If
 841 .Ar file
 842 is not executable, ignore it.
 843 .It
 844 If the
 845 .Xr rc.conf 5
 846 variable
 847 .Va rc_fast_and_loose
 848 is empty,
 849 source
 850 .Ar file
 851 in a sub shell,
 852 otherwise source
 853 .Ar file
 854 into the current shell.
 855 .El
 856 .It Ic stop_boot Op Ar always
 857 Prevent booting to multiuser mode.
 858 If the
 859 .Va autoboot
 860 variable is set to
 861 .Ql yes ,
 862 or
 863 .Ic checkyesno Ar always
 864 indicates a truth value, then a
 865 .Dv SIGTERM
 866 signal is sent to the parent
 867 process, which is assumed to be
 868 .Xr rc 8 .
 869 Otherwise, the shell exits with a non-zero status.
 870 .It Ic wait_for_pids Op Ar pid ...
 871 Wait until all of the provided
 872 .Ar pids
 873 do not exist any more, printing the list of outstanding
 874 .Ar pids
 875 every two seconds.
 876 .It Ic warn Ar message
 877 Display a warning message to
 878 .Va stderr
 879 and log it to the system log
 880 using
 881 .Xr logger 1 .
 882 The warning message consists of the script name
 883 (from
 884 .Va $0 ) ,
 885 followed by
 886 .Dq Li ": WARNING: " ,
 887 and then
 888 .Ar message .
 889 .El
 890 .Sh FILES
 891 .Bl -tag -width ".Pa /etc/rc.subr" -compact
 892 .It Pa /etc/rc.subr
 893 The
 894 .Nm
 895 file resides in
 896 .Pa /etc .
 897 .El
 898 .Sh SEE ALSO
 899 .Xr rc.conf 5 ,
 900 .Xr rc 8
 901 .Sh HISTORY
 902 The
 903 .Nm
 904 script
 905 appeared in
 906 .Nx 1.3 .
 907 The
 908 .Xr rc.d 8
 909 support functions appeared in
 910 .Nx 1.5 .
 911 The
 912 .Nm
 913 script
 914 first appeared in
 915 .Fx 5.0 .