/share/man/man8/rc.subr.8

https://bitbucket.org/freebsd/freebsd-head/ · Unknown · 878 lines · 878 code · 0 blank · 0 comment · 0 complexity · e19a9fc3917a1938a0fac4c342dc734f MD5 · raw file

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