share/man/man8/rc.subr.8

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