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