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 September 23, 2012
  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}_flags
 572 Arguments to call
 573 .Va command
 574 with.
 575 This is usually set in
 576 .Xr rc.conf 5 ,
 577 and not in the
 578 .Xr rc.d 8
 579 script.
 580 The environment variable
 581 .Sq Ev flags
 582 can be used to override this.
 583 .It Va ${name}_nice
 584 .Xr nice 1
 585 level to run
 586 .Va command
 587 as.
 588 Only supported after
 589 .Pa /usr
 590 is mounted.
 591 .It Va ${name}_program
 592 Full path to the command.
 593 Overrides
 594 .Va command
 595 if both are set, but has no effect if
 596 .Va command
 597 is unset.
 598 As a rule,
 599 .Va command
 600 should be set in the script while
 601 .Va ${name}_program
 602 should be set in
 603 .Xr rc.conf 5 .
 604 .It Va ${name}_user
 605 User to run
 606 .Va command
 607 as, using
 608 .Xr chroot 8
 609 if
 610 .Va ${name}_chroot
 611 is set, otherwise
 612 uses
 613 .Xr su 1 .
 614 Only supported after
 615 .Pa /usr
 616 is mounted.
 617 .It Va ${name}_group
 618 Group to run the chrooted
 619 .Va command
 620 as.
 621 .It Va ${name}_groups
 622 Comma separated list of supplementary groups to run the chrooted
 623 .Va command
 624 with.
 625 .It Ar argument Ns Va _cmd
 626 Shell commands which override the default method for
 627 .Ar argument .
 628 .It Ar argument Ns Va _precmd
 629 Shell commands to run just before running
 630 .Ar argument Ns Va _cmd
 631 or the default method for
 632 .Ar argument .
 633 If this returns a non-zero exit code, the main method is not performed.
 634 If the default method is being executed, this check is performed after
 635 the
 636 .Va required_*
 637 checks and process (non-)existence checks.
 638 .It Ar argument Ns Va _postcmd
 639 Shell commands to run if running
 640 .Ar argument Ns Va _cmd
 641 or the default method for
 642 .Ar argument
 643 returned a zero exit code.
 644 .It Va sig_stop
 645 Signal to send the processes to stop in the default
 646 .Cm stop
 647 method.
 648 Defaults to
 649 .Dv SIGTERM .
 650 .It Va sig_reload
 651 Signal to send the processes to reload in the default
 652 .Cm reload
 653 method.
 654 Defaults to
 655 .Dv SIGHUP .
 656 .El
 657 .Pp
 658 For a given method
 659 .Ar argument ,
 660 if
 661 .Ar argument Ns Va _cmd
 662 is not defined, then a default method is provided by
 663 .Ic run_rc_command :
 664 .Bl -tag -width ".Sy Argument" -offset indent
 665 .It Sy Argument
 666 .Sy Default method
 667 .It Cm start
 668 If
 669 .Va command
 670 is not running and
 671 .Ic checkyesno Va rcvar
 672 succeeds, start
 673 .Va command .
 674 .It Cm stop
 675 Determine the PIDs of
 676 .Va command
 677 with
 678 .Ic check_pidfile
 679 or
 680 .Ic check_process
 681 (as appropriate),
 682 .Ic kill Va sig_stop
 683 those PIDs, and run
 684 .Ic wait_for_pids
 685 on those PIDs.
 686 .It Cm reload
 687 Similar to
 688 .Cm stop ,
 689 except that it uses
 690 .Va sig_reload
 691 instead, and does not run
 692 .Ic wait_for_pids .
 693 Another difference from
 694 .Cm stop
 695 is that
 696 .Cm reload
 697 is not provided by default.
 698 It can be enabled via
 699 .Va extra_commands
 700 if appropriate:
 701 .Pp
 702 .Dl "extra_commands=reload"
 703 .It Cm restart
 704 Runs the
 705 .Cm stop
 706 method, then the
 707 .Cm start
 708 method.
 709 .It Cm status
 710 Show the PID of
 711 .Va command ,
 712 or some other script specific status operation.
 713 .It Cm poll
 714 Wait for
 715 .Va command
 716 to exit.
 717 .It Cm rcvar
 718 Display which
 719 .Xr rc.conf 5
 720 variable is used (if any).
 721 This method always works, even if the appropriate
 722 .Xr rc.conf 5
 723 variable is set to
 724 .Dq Li NO .
 725 .El
 726 .Pp
 727 The following variables are available to the methods
 728 (such as
 729 .Ar argument Ns Va _cmd )
 730 as well as after
 731 .Ic run_rc_command
 732 has completed:
 733 .Bl -tag -width ".Va rc_flags" -offset indent
 734 .It Va rc_arg
 735 Argument provided to
 736 .Ic run_rc_command ,
 737 after fast and force processing has been performed.
 738 .It Va rc_flags
 739 Flags to start the default command with.
 740 Defaults to
 741 .Va ${name}_flags ,
 742 unless overridden by the environment variable
 743 .Sq Ev flags .
 744 This variable may be changed by the
 745 .Ar argument Ns Va _precmd
 746 method.
 747 .It Va rc_pid
 748 PID of
 749 .Va command
 750 (if appropriate).
 751 .It Va rc_fast
 752 Not empty if
 753 .Dq Li fast
 754 prefix was used.
 755 .It Va rc_force
 756 Not empty if
 757 .Dq Li force
 758 prefix was used.
 759 .El
 760 .It Ic run_rc_script Ar file argument
 761 Start the script
 762 .Ar file
 763 with an argument of
 764 .Ar argument ,
 765 and handle the return value from the script.
 766 .Pp
 767 Various shell variables are unset before
 768 .Ar file
 769 is started:
 770 .Bd -ragged -offset indent
 771 .Va name ,
 772 .Va command ,
 773 .Va command_args ,
 774 .Va command_interpreter ,
 775 .Va extra_commands ,
 776 .Va pidfile ,
 777 .Va rcvar ,
 778 .Va required_dirs ,
 779 .Va required_files ,
 780 .Va required_vars ,
 781 .Ar argument Ns Va _cmd ,
 782 .Ar argument Ns Va _precmd .
 783 .Ar argument Ns Va _postcmd .
 784 .Ed
 785 .Pp
 786 The startup behaviour of
 787 .Ar file
 788 depends upon the following checks:
 789 .Bl -enum
 790 .It
 791 If
 792 .Ar file
 793 ends in
 794 .Pa .sh ,
 795 it is sourced into the current shell.
 796 .It
 797 If
 798 .Ar file
 799 appears to be a backup or scratch file
 800 (e.g., with a suffix of
 801 .Pa ~ , # , .OLD ,
 802 or
 803 .Pa .orig ) ,
 804 ignore it.
 805 .It
 806 If
 807 .Ar file
 808 is not executable, ignore it.
 809 .It
 810 If the
 811 .Xr rc.conf 5
 812 variable
 813 .Va rc_fast_and_loose
 814 is empty,
 815 source
 816 .Ar file
 817 in a sub shell,
 818 otherwise source
 819 .Ar file
 820 into the current shell.
 821 .El
 822 .It Ic stop_boot Op Ar always
 823 Prevent booting to multiuser mode.
 824 If the
 825 .Va autoboot
 826 variable is set to
 827 .Ql yes ,
 828 or
 829 .Ic checkyesno Ar always
 830 indicates a truth value, then a
 831 .Dv SIGTERM
 832 signal is sent to the parent
 833 process, which is assumed to be
 834 .Xr rc 8 .
 835 Otherwise, the shell exits with a non-zero status.
 836 .It Ic wait_for_pids Op Ar pid ...
 837 Wait until all of the provided
 838 .Ar pids
 839 do not exist any more, printing the list of outstanding
 840 .Ar pids
 841 every two seconds.
 842 .It Ic warn Ar message
 843 Display a warning message to
 844 .Va stderr
 845 and log it to the system log
 846 using
 847 .Xr logger 1 .
 848 The warning message consists of the script name
 849 (from
 850 .Va $0 ) ,
 851 followed by
 852 .Dq Li ": WARNING: " ,
 853 and then
 854 .Ar message .
 855 .El
 856 .Sh FILES
 857 .Bl -tag -width ".Pa /etc/rc.subr" -compact
 858 .It Pa /etc/rc.subr
 859 The
 860 .Nm
 861 file resides in
 862 .Pa /etc .
 863 .El
 864 .Sh SEE ALSO
 865 .Xr rc.conf 5 ,
 866 .Xr rc 8
 867 .Sh HISTORY
 868 The
 869 .Nm
 870 script
 871 appeared in
 872 .Nx 1.3 .
 873 The
 874 .Xr rc.d 8
 875 support functions appeared in
 876 .Nx 1.5 .
 877 The
 878 .Nm
 879 script
 880 first appeared in
 881 .Fx 5.0 .