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 .\" $DragonFly: src/share/man/man8/rc.subr.8,v 1.6 2008/09/06 21:31:21 swildner Exp $
4 .\" Copyright (c) 2002 The NetBSD Foundation, Inc.
5 .\" All rights reserved.
7 .\" This code is derived from software contributed to The NetBSD Foundation
10 .\" Redistribution and use in source and binary forms, with or without
11 .\" modification, are permitted provided that the following conditions
13 .\" 1. Redistributions of source code must retain the above copyright
14 .\" notice, this list of conditions and the following disclaimer.
15 .\" 2. Redistributions in binary form must reproduce the above copyright
16 .\" notice, this list of conditions and the following disclaimer in the
17 .\" documentation and/or other materials provided with the distribution.
18 .\" 3. All advertising materials mentioning features or use of this software
19 .\" must display the following acknowledgement:
20 .\" This product includes software developed by the NetBSD
21 .\" Foundation, Inc. and its contributors.
22 .\" 4. Neither the name of The NetBSD Foundation nor the names of its
23 .\" contributors may be used to endorse or promote products derived
24 .\" from this software without specific prior written permission.
26 .\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
27 .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
28 .\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
29 .\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
30 .\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
31 .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
32 .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
33 .\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
34 .\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
35 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
36 .\" POSSIBILITY OF SUCH DAMAGE.
43 .Nd functions used by system shell scripts
49 .Ic backup_file Ar action Ar file Ar current Ar backup
53 .Ic check_pidfile Ar pidfile Ar procname Op Ar interpreter
55 .Ic check_process Ar procname Op Ar interpreter
59 .Ic err Ar exitval Ar message
61 .Ic force_depend Ar name
65 .Ic load_rc_config Ar command
67 .Ic mount_critical_filesystems Ar type
69 .Ic rc_usage Ar command Op Ar ...
71 .Ic reverse_list Ar item Op Ar ...
73 .Ic run_rc_command Ar argument
75 .Ic run_rc_script Ar file Ar argument
77 .Ic set_rcvar Op Ar base
79 .Ic wait_for_pids Op Ar pid Op Ar ...
85 contains commonly used shell script functions and variable
86 definitions which are used by various scripts such as
91 functions were mostly imported from
93 and it is intended that they remain synced between the
94 two projects. With that in mind there are several variable
95 definitions that can help in this regard. They are:
98 Its value will be either
103 depending on which OS it is running on.
109 The path and argument list to display only the
111 values instead of a name=value pair.
113 The path and argument to write or modify
120 functions are accessed by sourcing
122 into the current shell.
124 The following shell functions are available:
127 .Ic backup_file Ar action Ar file Ar current Ar backup
129 Make a backup copy of
141 to archive the previous version of
143 otherwise save the previous version of
149 may be one of the following:
150 .Bl -tag -width remove
153 is now being backed up by or possibly re-entered into this backup mechanism.
155 is created, and if necessary, the
157 files are created as well.
160 has changed and needs to be backed up.
163 exists, it is copied to
167 (if the repository file is old),
174 is no longer being tracked by this backup mechanism.
177 is being used, an empty file is checked in and
185 .It Ic checkyesno Ar var
204 is not set correctly.
205 The values are case insensitive.
212 Parses the first word of the first line of
214 for a PID, and ensures that the process with that PID
215 is running and its first argument matches
217 Prints the matching PID if successful, otherwise nothing.
220 is provided, parse the first line of
222 ensure that the line is of the form
223 .Dl #! interpreter [...]
226 with its optional arguments and
228 appended as the process string to search for.
229 .It Ic check_process Ar procname Op Ar interpreter
230 Prints the PIDs of any processes that are running with a first
231 argument that matches
236 .It Ic debug Ar message
237 Display a debugging message to
239 log it to the system log using
242 return to the caller.
243 The error message consists of the script name
250 This function is intended to be used by developers
251 as an aid to debugging scripts. It can be turned on or off
256 .It Ic err Ar exitval Ar message
257 Display an error message to
259 log it to the system log
264 with an exit value of
266 The error message consists of the script name
273 .It Ic force_depend name
274 Output an advisory message and force the
276 service to start. The
280 component of the path to the script, usually
282 If the script fails for any reason it will output a warning
283 and return with a return value of 1. If it was successful
285 .It Ic info Ar message
286 Display an informational message to
288 and log it to the system log using
290 The message consists of the script name
297 The display of this informational output can be
298 turned on or off by the
302 .It Ic load_rc_config Ar command
303 Source in the configuration files for
307 is sourced if it has not yet been read in.
309 .Pa /etc/rc.conf.d/ Ns Ar command
310 is sourced if it is an existing file.
311 The latter may also contain other variable assignments to override
313 arguments defined by the calling script, to provide an easy
314 mechanism for an administrator to override the behaviour of a given
316 script without requiring the editing of that script.
317 .It Ic mount_critical_filesystems Ar type
318 Go through a list of critical file systems,
322 .Sy critical_filesystems_ Ns Ar type ,
323 mounting each one that
324 is not currently mounted.
325 .It Ic rc_usage Ar command Op Ar ...
326 Print a usage message for
330 being the list of valid arguments
333 .It Ic reverse_list Ar item Op Ar ...
337 .It Ic run_rc_command Ar argument
340 method for the current
342 script, based on the settings of various shell variables.
344 is extremely flexible, and allows fully functional
346 scripts to be implemented in a small amount of shell code.
349 is searched for in the list of supported commands, which may be one
351 .Dl start stop restart rcvar
352 as well as any word listed in the optional variable
362 may have one of the following prefixes which alters its operation:
363 .Bl -tag -width "Prefix" -offset indent -compact
367 Skip the check for an existing running process,
377 .Ar argument Ns Sy _precmd
378 returning non-zero, and ignores any of the
384 uses the following shell variables to control its behaviour.
385 Unless otherwise stated, these are optional.
386 .Bl -tag -width procname -offset indent
388 The name of this script.
389 This is not optional.
395 to determine if this method should be run.
397 Full path to the command.
399 .Ar argument Ns Sy _cmd
400 is defined for each supported keyword.
402 Optional arguments and/or shell directives for
404 .It Sy command_interpreter
407 .Dl #! command_interpreter [...]
411 .Dl command_interpreter [...] command
412 so use that string to find the PID(s) of the running command
415 .It Sy extra_commands
416 Extra commands/keywords/arguments supported.
419 Used to determine the PID(s) of the running command.
423 .Dl check_pidfile $pidfile $procname
428 .Dl check_process $procname
431 Process name to check for.
432 Defaults to the value of
435 Check for the existence of the listed directories
436 before running the default start method.
437 .It Sy required_files
438 Check for the readability of the listed files
439 before running the default start method.
443 on each of the list variables
444 before running the default start method.
453 .It Sy ${name}_chroot
465 This is usually set in
470 The environment variable
472 can be used to override this.
495 Group to run the chrooted
498 .It Sy ${name}_groups
499 Comma separated list of supplementary groups to run the chrooted
502 .It Ar argument Ns Sy _cmd
503 Shell commands which override the default method for
505 .It Ar argument Ns Sy _precmd
506 Shell commands to run just before running
507 .Ar argument Ns Sy _cmd
508 or the default method for
510 If this returns a non-zero exit code, the main method is not performed.
511 If the default method is being executed, this check is performed after
514 checks and process (non-)existence checks.
515 .It Ar argument Ns Sy _postcmd
516 Shell commands to run if running
517 .Ar argument Ns Sy _cmd
518 or the default method for
520 returned a zero exit code.
522 Signal to send the processes to stop in the default
528 Signal to send the processes to reload in the default
538 .Ar argument Ns Sy _cmd
539 is not defined, then a default method is provided by
541 .Bl -tag -width "argument" -offset indent
548 .Ic checkyesno Sy rcvar
552 Determine the PIDs of
568 instead, and doesn't run
579 or some other script specific status operation.
587 variable is used (if any).
588 This method always works, even if the appropriate
594 The following variables are available to the methods
596 .Ar argument Ns Sy _cmd )
600 .Bl -tag -width "rc_flags" -offset indent
604 after fast and force processing has been performed.
606 Flags to start the default command with.
609 unless overridden by the environment variable
611 This variable may be changed by the
612 .Ar argument Ns Sy _precmd
627 .It Ic run_rc_script Ar file Ar argument
632 and handle the return value from the script.
634 Various shell variables are unset before
637 .Bd -ragged -offset indent
641 .Sy command_interpreter ,
648 .Ar argument Ns Sy _cmd ,
649 .Ar argument Ns Sy _precmd .
650 .Ar argument Ns Sy _postcmd .
653 The startup behaviour of
655 depends upon the following checks:
662 it is sourced into the current shell.
666 appears to be a backup or scratch file
667 (e.g., with a suffix of
677 is not executable, ignore it.
682 .Sy rc_fast_and_loose
689 into the current shell.
691 .It Ic set_rcvar Op Ar base
692 Set the variable name required to start a service. In
694 a daemon is usually controlled by an
696 variable consisting of a daemon's name optionally postfixed by the string
698 When the following line is included in a script
700 .Dl rcvar=`set_rcvar`
702 This function will use the value of the
704 variable, which should be defined by the calling script, to construct the appropriate
708 argument is set it will use
712 .It Ic wait_for_pids Op Ar pid Op Ar ...
713 Wait until all of the provided
715 don't exist any more, printing the list of outstanding
718 .It Ic warn Ar message
719 Display a warning message to
721 and log it to the system log
724 The warning message consists of the script name
733 .Bl -tag -width /etc/rc.subr -compact
749 support functions appeared in