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