--- rc.pod 2002/01/31 10:11:43 1.25
+++ rc.pod 2002/01/31 21:14:10 1.26
@@ -52,10 +52,15 @@
[B<--RequireUmask umask>]
[B<--RequireOwner uid|name>]
[B<--RequireGroup gid|name>]
+[B<--ParseEnvAss regex>]
[B<--ParseSectionDef regex>]
[B<--ParseSectionRef regex>]
+[B<--ParseSectionParam regex>]
+[B<--ParseTerminal regex>]
[B<--NameConfig> name]
[B<--NameCommon> name]
+[B<--NameDefault> name]
+[B<--NameError> name]
I<rcfile>
I<section>
@@ -176,13 +181,25 @@
group of the F<rcfile> must match gid|name, otherwise it's ignored.
+=item B<--ParseConfigAss regex>
+
+regex matching the variable assignments in a F<rcfile>.
+
=item B<--ParseSectionDef regex>
-regex matching a section within a F<rcfile>.
+regex matching a section label in a F<rcfile>.
=item B<--ParseSectionRef regex>
-regex matching a reference within a F<rcfile>.
+regex matching a reference in a F<rcfile>.
+
+=item B<--ParseSectionParam regex>
+
+regex matching a section parameter in a F<rcfile>.
+
+=item B<--ParseTerminal regex>
+
+regex matching a terminal symbol in a F<rcfile>. See LANGUAGE.
=item B<--NameConfig> name
@@ -192,6 +209,14 @@
name of the common section, defaults to %common.
+=item B<--NameDefault> name
+
+name of the default section, defaults to %default.
+
+=item B<--NameError> name
+
+name of the error section, defaults to %error.
+
Every command line longoption corresponds to a keyword in the F<rc.conf> file.
When prefixed with 'OSSP_RC_' and its name in upper case, an option can be set
as an environment variable. First, options from the F<rc.conf> file are read.
@@ -206,17 +231,54 @@
'OSSP_RC_' and be all upper case. As a security measure, one environment
variable exists that is not found as an option elsewhere. This variable
deactivates B<OSSP rc>, and each subsequent usage will return success and
-print a 'No commands run: OSSP_RC_DEACT set to yes' error message to the
-standard output.
+write 'No commands run: OSSP_RC_DEACT set to yes' to the console and syslog
+with LOG_USER and LOG_ERR (see syslog(3)).
B<OSSP_RC_DEACT> - Set to 'yes' or 'true' to totally deactivate B<OSSP rc>
+=head1 COMMAND INTERPRETER
+
+As long as a valid interpreter path is specified in the section labels of a
+F<rcfile>, the runcommands resulting from a --eval, --exec, or --print
+operation can be written in any runtime-interpreted language. This means that
+a perl programmer can write runcommands in perl, and specify the perl
+interpreter path in the corresponding section label of the F<rcfile>. A
+different programming language can be used for each section, even though this
+would complicate inclusion of script from the B<%common> section and
+F<rc.func> sections (because each section is associated with only one
+interpreter). If the command interpreter in a section label is not specified,
+then the Bourne shell will be used by default. See FILES/rc.foo for details.
+
=head1 RETURN VALUE
-1 Error in rc
0 Success
1 Error in command executed by rc
+=head1 ERROR HANDLING
+
+Rich and fine-tuned error handling is possible by writing one or both of the
+following sections into F<rcfile>(s). These sections typically reference the
+local F<rcfile>'s variables ${rc_errcode} and ${rc_errstring} for more
+information about which error was encountered and its text.
+
+=item B<%error>
+
+If an error condition arises during an F<rcfile>'s processing, control will
+pass to the B<%error> section whose commands will begin to run. Should no such
+B<%error> section exist, rc will stop any rcfile processing and write error
+strings to the console and syslog using LOG_USER and LOG_ERR (see syslog(3)).
+An empty B<%error> section in each F<rcfile> is synonymous to a
+C<IgnoreAllErrors> option (which doesn't exist).
+
+=item B<%default>
+
+The commands in the B<%default> section are run when the corresponding
+F<rcfile> contains no section label matching the one(s) specified on the
+command line. If the appropriate section label doesn't exist and neither does
+B<%default>, then an error is assumed and control flows to the B<%error>
+section.
+
=head1 EXAMPLES
A runcommand consists of a single program name and one or more sections. The
@@ -227,16 +289,22 @@
/usr/local/bin/rc --info
/sbin/rc --query lmtp2nntp
/cw/etc/rc --conf /etc/rc.conf --debug smtpd stop
- /sfw/etc/rc --silent ntpd start sync stop start
+ /sfw/etc/rc.d/rc.ntpd --silent start sync stop start
/usr/local/bin/rc httpd reload # sends a HUP signal
-Arguments may also be passed in to B<OSSP rc>, which will forward them to each
-section as it is called.
-
- /mybin/rc sshd start LOG_USER # calls logger(1) and passes LOG_USER
- /etc/rc lmtp2nntp start 2 # sleep for 2 seconds before returning
- /etc/rc.d/rc.rsyncd restart 4 # leave a 4 second pause between start and stop
- /cw/etc/rc.d/rc.ftpd start 32 # a maximum of 32 users can connect
+Arguments in the form of name=value pairs may be passed to the section(s)
+given on the command line. In the F<rcfile>, such arguments will appear as
+normal configuration variables. They can be referenced as such (by default as
+${myarg}). On the command line, the arguments following a section will be
+local to the section and unusable by the others. If a argument is needed by
+more than one section, then repeat its definition after each section given on
+the command line.
+
+ /mybin/rc all start sFac="LOG_USER" # pass LOG_USER as an argument to 'start'
+ /etc/rc lmtp2nntp start nSleep=2 # sleep for 2 seconds before returning
+ /etc/rc.d/rc.rsyncd restart nSleep=4 # pause 4 seconds between start and stop
+ /cw/etc/rc.d/rc.ftpd start nMax=32 # a maximum of 32 users can connect
+ rc -rdv all stop nSleep=2 start nSleep=4 sLevel="LOG_INFO" bQuiet=1
To evaluate a runcommand for all programs with an identical section name, a
short expression can be written into a F<.profile> file. When the shell
@@ -259,7 +327,7 @@
more information, inspect the /etc/rc structures provided by the FreeBSD,
Solaris, and Red Hat distributions.
-rc-sample(5), rc.conf(1), and rcfile(1).
+rc-sample(5).
=head1 AUTHORS
|
