share/man/man8/rc.subr.8

   1 .\"     $NetBSD: rc.subr.8,v 1.12 2004/01/06 00:52:24 lukem Exp $
   2 .\"
   3 .\" Copyright (c) 2002-2004 The NetBSD Foundation, Inc.
   4 .\" All rights reserved.
   5 .\"
   6 .\" This code is derived from software contributed to The NetBSD Foundation
   7 .\" by Luke Mewburn.
   8 .\"
   9 .\" Redistribution and use in source and binary forms, with or without
  10 .\" modification, are permitted provided that the following conditions
  11 .\" are met:
  12 .\" 1. Redistributions of source code must retain the above copyright
  13 .\"    notice, this list of conditions and the following disclaimer.
  14 .\" 2. Redistributions in binary form must reproduce the above copyright
  15 .\"    notice, this list of conditions and the following disclaimer in the
  16 .\"    documentation and/or other materials provided with the distribution.
  17 .\"
  18 .\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
  19 .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
  20 .\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
  21 .\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
  22 .\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
  23 .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
  24 .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
  25 .\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
  26 .\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
  27 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
  28 .\" POSSIBILITY OF SUCH DAMAGE.
  29 .\"
  30 .\" $FreeBSD$
  31 .\"
  32 .Dd September 18, 2016
  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
 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}_oomprotect
 587 .Xr protect 1
 588 .Va command
 589 from being killed when swap space is exhausted.
 590 If
 591 .Em YES
 592 is used, no child processes are protected.
 593 If
 594 .Em ALL ,
 595 protect all child processes.
 596 .It Va ${name}_program
 597 Full path to the command.
 598 Overrides
 599 .Va command
 600 if both are set, but has no effect if
 601 .Va command
 602 is unset.
 603 As a rule,
 604 .Va command
 605 should be set in the script while
 606 .Va ${name}_program
 607 should be set in
 608 .Xr rc.conf 5 .
 609 .It Va ${name}_user
 610 User to run
 611 .Va command
 612 as, using
 613 .Xr chroot 8
 614 if
 615 .Va ${name}_chroot
 616 is set, otherwise
 617 uses
 618 .Xr su 1 .
 619 Only supported after
 620 .Pa /usr
 621 is mounted.
 622 .It Va ${name}_group
 623 Group to run the chrooted
 624 .Va command
 625 as.
 626 .It Va ${name}_groups
 627 Comma separated list of supplementary groups to run the chrooted
 628 .Va command
 629 with.
 630 .It Va ${name}_prepend
 631 Commands to be prepended to
 632 .Va command .
 633 This is a generic version of
 634 .Va ${name}_env ,
 635 .Va ${name}_fib ,
 636 or
 637 .Va ${name}_nice .
 638 .It Ar argument Ns Va _cmd
 639 Shell commands which override the default method for
 640 .Ar argument .
 641 .It Ar argument Ns Va _precmd
 642 Shell commands to run just before running
 643 .Ar argument Ns Va _cmd
 644 or the default method for
 645 .Ar argument .
 646 If this returns a non-zero exit code, the main method is not performed.
 647 If the default method is being executed, this check is performed after
 648 the
 649 .Va required_*
 650 checks and process (non-)existence checks.
 651 .It Ar argument Ns Va _postcmd
 652 Shell commands to run if running
 653 .Ar argument Ns Va _cmd
 654 or the default method for
 655 .Ar argument
 656 returned a zero exit code.
 657 .It Va sig_stop
 658 Signal to send the processes to stop in the default
 659 .Cm stop
 660 method.
 661 Defaults to
 662 .Dv SIGTERM .
 663 .It Va sig_reload
 664 Signal to send the processes to reload in the default
 665 .Cm reload
 666 method.
 667 Defaults to
 668 .Dv SIGHUP .
 669 .El
 670 .Pp
 671 For a given method
 672 .Ar argument ,
 673 if
 674 .Ar argument Ns Va _cmd
 675 is not defined, then a default method is provided by
 676 .Ic run_rc_command :
 677 .Bl -tag -width ".Sy Argument" -offset indent
 678 .It Sy Argument
 679 .Sy Default method
 680 .It Cm start
 681 If
 682 .Va command
 683 is not running and
 684 .Ic checkyesno Va rcvar
 685 succeeds, start
 686 .Va command .
 687 .It Cm stop
 688 Determine the PIDs of
 689 .Va command
 690 with
 691 .Ic check_pidfile
 692 or
 693 .Ic check_process
 694 (as appropriate),
 695 .Ic kill Va sig_stop
 696 those PIDs, and run
 697 .Ic wait_for_pids
 698 on those PIDs.
 699 .It Cm reload
 700 Similar to
 701 .Cm stop ,
 702 except that it uses
 703 .Va sig_reload
 704 instead, and does not run
 705 .Ic wait_for_pids .
 706 Another difference from
 707 .Cm stop
 708 is that
 709 .Cm reload
 710 is not provided by default.
 711 It can be enabled via
 712 .Va extra_commands
 713 if appropriate:
 714 .Pp
 715 .Dl "extra_commands=reload"
 716 .It Cm restart
 717 Runs the
 718 .Cm stop
 719 method, then the
 720 .Cm start
 721 method.
 722 .It Cm status
 723 Show the PID of
 724 .Va command ,
 725 or some other script specific status operation.
 726 .It Cm poll
 727 Wait for
 728 .Va command
 729 to exit.
 730 .It Cm rcvar
 731 Display which
 732 .Xr rc.conf 5
 733 variable is used (if any).
 734 This method always works, even if the appropriate
 735 .Xr rc.conf 5
 736 variable is set to
 737 .Dq Li NO .
 738 .El
 739 .Pp
 740 The following variables are available to the methods
 741 (such as
 742 .Ar argument Ns Va _cmd )
 743 as well as after
 744 .Ic run_rc_command
 745 has completed:
 746 .Bl -tag -width ".Va rc_flags" -offset indent
 747 .It Va rc_arg
 748 Argument provided to
 749 .Ic run_rc_command ,
 750 after fast and force processing has been performed.
 751 .It Va rc_flags
 752 Flags to start the default command with.
 753 Defaults to
 754 .Va ${name}_flags ,
 755 unless overridden by the environment variable
 756 .Sq Ev flags .
 757 This variable may be changed by the
 758 .Ar argument Ns Va _precmd
 759 method.
 760 .It Va rc_pid
 761 PID of
 762 .Va command
 763 (if appropriate).
 764 .It Va rc_fast
 765 Not empty if
 766 .Dq Li fast
 767 prefix was used.
 768 .It Va rc_force
 769 Not empty if
 770 .Dq Li force
 771 prefix was used.
 772 .El
 773 .It Ic run_rc_script Ar file argument
 774 Start the script
 775 .Ar file
 776 with an argument of
 777 .Ar argument ,
 778 and handle the return value from the script.
 779 .Pp
 780 Various shell variables are unset before
 781 .Ar file
 782 is started:
 783 .Bd -ragged -offset indent
 784 .Va name ,
 785 .Va command ,
 786 .Va command_args ,
 787 .Va command_interpreter ,
 788 .Va extra_commands ,
 789 .Va pidfile ,
 790 .Va rcvar ,
 791 .Va required_dirs ,
 792 .Va required_files ,
 793 .Va required_vars ,
 794 .Ar argument Ns Va _cmd ,
 795 .Ar argument Ns Va _precmd .
 796 .Ar argument Ns Va _postcmd .
 797 .Ed
 798 .Pp
 799 The startup behaviour of
 800 .Ar file
 801 depends upon the following checks:
 802 .Bl -enum
 803 .It
 804 If
 805 .Ar file
 806 ends in
 807 .Pa .sh ,
 808 it is sourced into the current shell.
 809 .It
 810 If
 811 .Ar file
 812 appears to be a backup or scratch file
 813 (e.g., with a suffix of
 814 .Pa ~ , # , .OLD ,
 815 or
 816 .Pa .orig ) ,
 817 ignore it.
 818 .It
 819 If
 820 .Ar file
 821 is not executable, ignore it.
 822 .It
 823 If the
 824 .Xr rc.conf 5
 825 variable
 826 .Va rc_fast_and_loose
 827 is empty,
 828 source
 829 .Ar file
 830 in a sub shell,
 831 otherwise source
 832 .Ar file
 833 into the current shell.
 834 .El
 835 .It Ic stop_boot Op Ar always
 836 Prevent booting to multiuser mode.
 837 If the
 838 .Va autoboot
 839 variable is set to
 840 .Ql yes ,
 841 or
 842 .Ic checkyesno Ar always
 843 indicates a truth value, then a
 844 .Dv SIGTERM
 845 signal is sent to the parent
 846 process, which is assumed to be
 847 .Xr rc 8 .
 848 Otherwise, the shell exits with a non-zero status.
 849 .It Ic wait_for_pids Op Ar pid ...
 850 Wait until all of the provided
 851 .Ar pids
 852 do not exist any more, printing the list of outstanding
 853 .Ar pids
 854 every two seconds.
 855 .It Ic warn Ar message
 856 Display a warning message to
 857 .Va stderr
 858 and log it to the system log
 859 using
 860 .Xr logger 1 .
 861 The warning message consists of the script name
 862 (from
 863 .Va $0 ) ,
 864 followed by
 865 .Dq Li ": WARNING: " ,
 866 and then
 867 .Ar message .
 868 .El
 869 .Sh FILES
 870 .Bl -tag -width ".Pa /etc/rc.subr" -compact
 871 .It Pa /etc/rc.subr
 872 The
 873 .Nm
 874 file resides in
 875 .Pa /etc .
 876 .El
 877 .Sh SEE ALSO
 878 .Xr rc.conf 5 ,
 879 .Xr rc 8
 880 .Sh HISTORY
 881 The
 882 .Nm
 883 script
 884 appeared in
 885 .Nx 1.3 .
 886 The
 887 .Xr rc.d 8
 888 support functions appeared in
 889 .Nx 1.5 .
 890 The
 891 .Nm
 892 script
 893 first appeared in
 894 .Fx 5.0 .