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.3 2007/03/03 23:19:25 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
88 Scripts required by ports in
89 .Pa /usr/local/etc/rc.d
91 be rewritten to make use of it.
95 functions were mostly imported from
97 and it is intended that they remain synced between the
98 two projects. With that in mind there are several variable
99 definitions that can help in this regard. They are:
102 Its value will be either
107 depending on which OS it is running on.
113 The path and argument list to display only the
115 values instead of a name=value pair.
117 The path and argument to write or modify
124 functions are accessed by sourcing
126 into the current shell.
128 The following shell functions are available:
131 .Ic backup_file Ar action Ar file Ar current Ar backup
133 Make a backup copy of
145 to archive the previous version of
147 otherwise save the previous version of
153 may be one of the following:
154 .Bl -tag -width remove
157 is now being backed up by or possibly re-entered into this backup mechanism.
159 is created, and if necessary, the
161 files are created as well.
164 has changed and needs to be backed up.
167 exists, it is copied to
171 (if the repository file is old),
178 is no longer being tracked by this backup mechanism.
181 is being used, an empty file is checked in and
189 .It Ic checkyesno Ar var
208 is not set correctly.
209 The values are case insensitive.
216 Parses the first word of the first line of
218 for a PID, and ensures that the process with that PID
219 is running and its first argument matches
221 Prints the matching PID if successful, otherwise nothing.
224 is provided, parse the first line of
226 ensure that the line is of the form
227 .Dl #! interpreter [...]
230 with its optional arguments and
232 appended as the process string to search for.
233 .It Ic check_process Ar procname Op Ar interpreter
234 Prints the PIDs of any processes that are running with a first
235 argument that matches
240 .It Ic debug Ar message
241 Display a debugging message to
243 log it to the system log using
246 return to the caller.
247 The error message consists of the script name
254 This function is intended to be used by developers
255 as an aid to debugging scripts. It can be turned on or off
260 .It Ic err Ar exitval Ar message
261 Display an error message to
263 log it to the system log
268 with an exit value of
270 The error message consists of the script name
277 .It Ic force_depend name
278 Output an advisory message and force the
280 service to start. The
284 component of the path to the script, usually
286 If the script fails for any reason it will output a warning
287 and return with a return value of 1. If it was successful
289 .It Ic info Ar message
290 Display an informational message to
292 and log it to the system log using
294 The message consists of the script name
301 The display of this informational output can be
302 turned on or off by the
306 .It Ic load_rc_config Ar command
307 Source in the configuration files for
311 is sourced if it has not yet been read in.
313 .Pa /etc/rc.conf.d/ Ns Ar command
314 is sourced if it is an existing file.
315 The latter may also contain other variable assignments to override
317 arguments defined by the calling script, to provide an easy
318 mechanism for an administrator to override the behaviour of a given
320 script without requiring the editing of that script.
321 .It Ic mount_critical_filesystems Ar type
322 Go through a list of critical file systems,
326 .Sy critical_filesystems_ Ns Ar type ,
327 mounting each one that
328 is not currently mounted.
329 .It Ic rc_usage Ar command Op Ar ...
330 Print a usage message for
334 being the list of valid arguments
337 .It Ic reverse_list Ar item Op Ar ...
341 .It Ic run_rc_command Ar argument
344 method for the current
346 script, based on the settings of various shell variables.
348 is extremely flexible, and allows fully functional
350 scripts to be implemented in a small amount of shell code.
353 is searched for in the list of supported commands, which may be one
355 .Dl start stop restart rcvar
356 as well as any word listed in the optional variable
366 may have one of the following prefixes which alters its operation:
367 .Bl -tag -width "Prefix" -offset indent -compact
371 Skip the check for an existing running process,
381 .Ar argument Ns Sy _precmd
382 returning non-zero, and ignores any of the
388 uses the following shell variables to control its behaviour.
389 Unless otherwise stated, these are optional.
390 .Bl -tag -width procname -offset indent
392 The name of this script.
393 This is not optional.
399 to determine if this method should be run.
401 Full path to the command.
403 .Ar argument Ns Sy _cmd
404 is defined for each supported keyword.
406 Optional arguments and/or shell directives for
408 .It Sy command_interpreter
411 .Dl #! command_interpreter [...]
415 .Dl command_interpreter [...] command
416 so use that string to find the PID(s) of the running command
419 .It Sy extra_commands
420 Extra commands/keywords/arguments supported.
423 Used to determine the PID(s) of the running command.
427 .Dl check_pidfile $pidfile $procname
432 .Dl check_process $procname
435 Process name to check for.
436 Defaults to the value of
439 Check for the existence of the listed directories
440 before running the default start method.
441 .It Sy required_files
442 Check for the readability of the listed files
443 before running the default start method.
447 on each of the list variables
448 before running the default start method.
457 .It Sy ${name}_chroot
469 This is usually set in
474 The environment variable
476 can be used to override this.
499 Group to run the chrooted
502 .It Sy ${name}_groups
503 Comma separated list of supplementary groups to run the chrooted
506 .It Ar argument Ns Sy _cmd
507 Shell commands which override the default method for
509 .It Ar argument Ns Sy _precmd
510 Shell commands to run just before running
511 .Ar argument Ns Sy _cmd
512 or the default method for
514 If this returns a non-zero exit code, the main method is not performed.
515 If the default method is being executed, this check is performed after
518 checks and process (non-)existence checks.
519 .It Ar argument Ns Sy _postcmd
520 Shell commands to run if running
521 .Ar argument Ns Sy _cmd
522 or the default method for
524 returned a zero exit code.
526 Signal to send the processes to stop in the default
532 Signal to send the processes to reload in the default
542 .Ar argument Ns Sy _cmd
543 is not defined, then a default method is provided by
545 .Bl -tag -width "argument" -offset indent
552 .Ic checkyesno Sy rcvar
556 Determine the PIDs of
572 instead, and doesn't run
583 or some other script specific status operation.
591 variable is used (if any).
592 This method always works, even if the appropriate
598 The following variables are available to the methods
600 .Ar argument Ns Sy _cmd )
604 .Bl -tag -width "rc_flags" -offset indent
608 after fast and force processing has been performed.
610 Flags to start the default command with.
613 unless overridden by the environment variable
615 This variable may be changed by the
616 .Ar argument Ns Sy _precmd
631 .It Ic run_rc_script Ar file Ar argument
636 and handle the return value from the script.
638 Various shell variables are unset before
641 .Bd -ragged -offset indent
645 .Sy command_interpreter ,
652 .Ar argument Ns Sy _cmd ,
653 .Ar argument Ns Sy _precmd .
654 .Ar argument Ns Sy _postcmd .
657 The startup behaviour of
659 depends upon the following checks:
666 it is sourced into the current shell.
670 appears to be a backup or scratch file
671 (e.g., with a suffix of
681 is not executable, ignore it.
686 .Sy rc_fast_and_loose
693 into the current shell.
695 .It Ic set_rcvar Op Ar base
696 Set the variable name required to start a service. In
698 a daemon is usually controlled by an
700 variable consisting of a daemon's name postfixed by the string
702 This is not the case in
704 When the following line is included in a script
706 .Dl rcvar=`set_rcvar`
708 This function will use the value of the
710 variable, which should be defined by the calling script, to construct the appropriate
714 argument is set it will use
718 .It Ic wait_for_pids Op Ar pid Op Ar ...
719 Wait until all of the provided
721 don't exist any more, printing the list of outstanding
724 .It Ic warn Ar message
725 Display a warning message to
727 and log it to the system log
730 The warning message consists of the script name
739 .Bl -tag -width /etc/rc.subr -compact
755 support functions appeared in