--- rc.pod 2002/01/29 15:35:05 1.23
+++ rc.pod 2002/01/30 22:55:26 1.24
@@ -1,5 +1,5 @@
##
-## rc.pod -- OSSP Run Command Processor (Manual Page)
+## rc.pod -- OSSP Runcommand Processor (Manual Page)
## Copyright (c) 2000-2002 Cable & Wireless Deutschland GmbH
## Copyright (c) 2000-2002 The OSSP Project <http://www.ossp.org/>
## Copyright (c) 2000-2002 Ralf S. Engelschall <rse@engelschall.com>
@@ -29,7 +29,7 @@
=over 4
-B<rc> - OSSP Run Command Processor
+B<rc> - OSSP Runcommand Processor
=back 4
@@ -71,24 +71,23 @@
=over 4
-OSSP rc is a run command processor. It's primary function is to scan
-F<rcfile> script files for B<section>(s) and run the commands listed in the
-section(s).
+OSSP rc is a runcommand processor. Its primary function is to scan F<rcfile>
+script files for B<section>(s) and run the commands listed in the section(s).
-The run command processor can alternatively print the commands in human
+The runcommand processor can alternatively print the commands in human
readable format or reformat them for shell C<eval> input without executing
them. The F<rcfile> files contain variables and the command processor has
functionality to query their default, set and effective values.
The structure of the F<rcfile>s is simple but the syntax is highly
-configurable. A F<rcfile> is divided into B<section>s and each of them is
-identified by a label build from the B<section> name. The distribution
+configurable. A F<rcfile> is divided into B<section>s and each of them is
+identified by a label build from the B<section> name. The distribution
contains various examples.
With a single call to rc usually one F<rcfile> may be processed at, although
-many sections can be passed which are executed in given order. The only
-exception to this rule is when the reserved keyword `all' is used as F<rcfile>
-meaning `all F<rcfile>s.'
+many B<sections> can be passed which are executed in given order. The only
+exception to this rule is when the reserved keyword 'all' is used as F<rcfile>
+meaning 'all F<rcfile>s.'
=back 4
@@ -106,8 +105,8 @@
=item B<-L>|B<--locate> I<file>[C<:>I<part>]
locations to search for F<rcfile>s where I<file> can contain regex patterns to
-filter files and the optional part is a regex to filter out parts of a file.
-This option can be specified more than once.
+filter files. The trailing part (after the ':') is a regex filter used to
+ignore parts of a file. This option can be specified more than once.
=item B<-V>|B<--version>
@@ -115,8 +114,10 @@
=item B<-c>|B<--conf> I<file>[C<:>I<file>[...]]
-specify the location of the configuration file. If omitted, the fallback is
-to look for C<$OSSP_RC_CONF>, and "@l_prefix@/etc/rc.conf", in that order.
+specify the location of the configuration file. If omitted, C<$OSSP_RC_CONF>
+will be examined. If absent, F<@l_prefix@/etc/rc.conf> will be used. If no
+F<rc.conf> exists at all, then only command line and environment specified
+options will override the defaults built-in to OSSP rc.
=item B<-e>|B<--eval>
@@ -151,9 +152,9 @@
=item B<-r>|B<--raw>
-output text using no terminal control sequences. The rc facility usually
+output text using no terminal control sequences. The rc facility usually
tries to improve output text for human readability using terminal control
-sequences for color, bold and italic rendering. The default is determines at
+sequences for color, bold and italic rendering. The default is determines at
runtime and is automagically disabled if stdout is detached from a terminal.
=item B<-s>|B<--silent>
@@ -162,7 +163,7 @@
=item B<-t>|B<--tmp> I<dir>
-specify the location of the temporary directory. If omitted, the fallback is
+specify the location of the temporary directory. If omitted, the fallback is
to look for C<$TMPDIR>, C<$TMPDIR>, try using C<~/tmp> and C</tmp>, in that
order.
@@ -206,13 +207,20 @@
=back 4
+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.
+Then, options from the environment are read. Last, options from the command
+line are read. This allows for flexibility when wishing to set a standard set
+of OSSP rc options, and override them conditionally.
+
=head1 ENVIRONMENT
=over 4
-Every command line longoption is also a keyword in the F<rc.conf> file and,
-prefixed with "OSSP_RC_" and it's name in upper case, also available as an
-environment variable.
+The environment contains options just as the command line and F<rc.conf> file
+does. An option's corresponding environment variable name must start with
+'OSSP_RC_' and be all upper case.
=back 4
@@ -228,55 +236,68 @@
=head1 EXAMPLES
-=over 4
-
-Some short one line examples include the following. Note that a run command
-consists of a single program name and one or more sections. The wildcard `all'
-can be given in place of a program name to denote all programs with entries in
-the rc registry F<$OSSP_RC_ROOT/rc.d>.
+A runcommand consists of a single program name and one or more sections. The
+wildcard 'all' can be given in place of a program name to denote all programs
+with entries in the rc registry F<$OSSP_RC_ROOT/rc.d>. The following are
+one-line examples of commonly used rc commands.
/usr/local/bin/rc --info
- /etc/rc --query lmtp2nntp
- /mybin/rc sshd start
- /etc/rc lmtp2nntp start
- /sfw/etc/rc --conf /etc/rc.conf --debug smtpd stop
+ /sbin/rc --query lmtp2nntp
+ /cw/etc/rc --conf /etc/rc.conf --debug smtpd stop
+ /mybin/rc sshd start LOG_USER # calls logger(1) and passes LOG_USER
+ /etc/rc lmtp2nntp start 2 # sleep for 2 seconds before returning
/sfw/etc/rc --silent ntpd start sync stop start
- /usr/local/bin/rc httpd restart
+ /usr/local/bin/rc httpd reload # sends a HUP signal
+ /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
-To evaluate a run command for all programs with an identical section name, a
+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
-initializes itself, the run commands will execute according to the C<eval>
+initializes itself, the runcommands will execute according to the C<eval(1)>
command. This is often seen when importing the environment of packages of an
-B<OpenPKG> hierarchy.
+B<OpenPKG> hierarchy, but is always a custom modification made by the user.
+
+ $ eval `@l_prefix@/etc/rc --eval all env`
=head1 FILES
-F<rc.conf> - Master configuration file
-F<rc.func> - User defined functions library
-F<rc.env> - Postprocess variable declaration file
-F<rc.foo> - Run commands for "foo" application
+=over 4
+
+F<rc.conf> - Master configuration file
+F<rc.func> - User defined functions library
+F<rc.env> - Postprocess variable declaration file
+F<rc.foo> - Runcommands for 'foo' application
+
+=back 4
=head1 SEE ALSO
-OSSP rc integrates concepts taken from other run command architectures. For
-more information, inspect the /etc/rc structures provided by FreeBSD, Solaris,
-and Red Hat distributions.
+=over 4
-rc.conf(1), rc.func(1), rc.env(1), rcfile(1), and rc-sample(1).
+OSSP rc integrates concepts taken from other runcommand architectures. For
+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).
+
+=back 4
=head1 AUTHORS
-Ralf S. Engelschall
+=over 4
+Ralf S. Engelschall
Michael Schloh von Bennewitz
+=back 4
+
=head1 HISTORY
-B<OSSP rc> is a replacement for the prototype run command facility used in the
-OpenPKG project (http://www.openpkg.org/). The prototype was a slow and less
-robust Bourne shell script. B<OSSP rc> is intended to faster, more robust, and
-more flexible. This flexibility allows for wider range of use, however. B<OSSP
-rc> can therefore be used in a variety of situations, and is no longer
-exclusive to the OpenPKG project.
+B<OSSP rc> is a drop-in replacement for the prototype runcommand facility used
+in OpenPKG (http://www.openpkg.org/). The prototype was a slow and less robust
+Bourne shell script. B<OSSP rc> is comparitively faster, more robust, and more
+flexible. This flexibility allows for wider range of use, and B<OSSP rc> can
+therefore be used in a variety of situations. It is no longer exclusive to the
+OpenPKG project.
=cut
|
