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