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