--- rc.pod 2002/01/21 18:14:54 1.5
+++ rc.pod 2002/01/22 18:00:59 1.6
@@ -1,7 +1,7 @@
##
-## rc.pod -- OpenPKG Run-Command Facility (Manual Page)
+## rc.pod -- OSSP Run Command Facility (Manual Page)
## Copyright (c) 2000-2002 Cable & Wireless Deutschland GmbH
-## Copyright (c) 2000-2002 The OpenPKG Project <http://www.openpkg.org/>
+## Copyright (c) 2000-2002 The OSSP Project <http://www.ossp.org/>
## Copyright (c) 2000-2002 Ralf S. Engelschall <rse@engelschall.com>
##
## Permission to use, copy, modify, and distribute this software for
@@ -23,18 +23,11 @@
## SUCH DAMAGE.
##
-# ref: %start; %stop
-# cfg
-# --glob-rcfile='rc.%s'
-# --regex-section='(?<=^|\n)%%%s\s*\n(.+?)(?=\n%\S+|$)'
-# --regex-reference='(?<=^|\n)%%%s\s*(.+?)(?=\n|;)'
-# def --showdefault, --defsetion=config
-
=pod
=head1 NAME
-B<rc> - OpenPKG Run-Command Facility
+B<rc> - OSSP Run Command Facility
=head1 SYNOPSIS
@@ -57,58 +50,63 @@
Although only one section is possible for each call to OSSP rc, many
`commands' can follow the section label. This allows for an abbreviated input
format when calling the same script section of many commands. An example of
-this is given in (EXAMPLES.)
+this is given in `EXAMPLES.'
=head1 OPTIONS
+=over 4
+
Inclusive options which may be used with another
--v, --verbose
+=item B<-c>, B<--config>
+ locate the configuration file in the following path,
+ overriding the environment variable $OSSP_RC_ROOT when
+ locating the configuration file
+
+=item B<-v>, B<--verbose>
verbosely report processing, including all warnings
--s, --silent
+=item B<-s>, B<--silent>
hold silence, and output no text messages whatsoever
--d, --debug
- don't remove any temporary files, and output debug messages
+=item B<-d>, B<--debug>
+ don't remove temporary files, and output debug messages to stderr
--r, --raw
+=item B<-r>, B<--raw>
output text using no terminal control sequences
Mutually exclusive options, i.e. only a single one can be given
--h, --help
+=item B<-h>, B<--help>
print this help, then exit
--V, --version
- print version number, then exit
-
--c, --config
- locate the configuration file in the following path,
- overriding the environment variable $OSSP_RC_ROOT when
- locating the configuration file
+=item B<-V>, B<--version>
+ print version and copyright, then exit
--p, --print
+=item B<-p>, B<--print>
output the text as it would be interpreted
by the shell, but do not run the commands
--e, --eval
+=item B<-e>, B<--eval>
output the text for a command suitable for shell evaluation
--x, --exec
- execute in subshell(s), follow with <package> <section>
+=item B<-x>, B<--exec>
+ execute in subshell(s), follow with <program> <section>
--q, --query
+=item B<-q>, B<--query>
print the value(s) of rc configuration variables
--l, --labels
+=item B<-l>, B<--labels>
learn what section labels a run command extends
--i, --info
+=item B<-i>, B<--info>
print a comprehensive summary of the rc environment
-All of these options have reasonable default values,
-which OSSP rc assumes when no option is otherwise given.
+All of these options have reasonable default values, which OSSP rc assumes
+when no option is otherwise given. For details of each listed option see
+`NOTES'.
+
+=back 4
=head1 RETURN VALUE
@@ -127,10 +125,26 @@
=head1 EXAMPLES
-/myetc/rc start sshd
-/etc/rc close docview primary httpd sshd radiusd
-/sfw/etc/rc restart smtpd lmtp2nntp
-/cw/etc/rc restart apache
+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>.
+
+ /usr/local/bin/rc --info
+ /etc/rc --query lmtp2nntp
+ /mybin/rc sshd start
+ /etc/rc lmtp2nntp start
+ /sfw/etc/rc --config /etc/rc.conf --debug smtpd stop
+ /sfw/etc/rc --silent ntpd start sync stop start
+ /usr/local/bin/rc httpd restart
+
+To evaluate a run command 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>
+command. This is often seen when importing the environment of packages of an
+B<OpenPKG> hierarchy.
+
+ $ eval `@l_prefix@/etc/rc --eval all env`
=head1 ENVIRONMENT
@@ -167,7 +181,14 @@
=head1 NOTES
-=over 4
+=nada
+
+# ref: %start; %stop
+# cfg
+# --glob-rcfile='rc.%s'
+# --regex-section='(?<=^|\n)%%%s\s*\n(.+?)(?=\n%\S+|$)'
+# --regex-reference='(?<=^|\n)%%%s\s*(.+?)(?=\n|;)'
+# def --showdefault, --defsetion=config
=item B<General>
@@ -233,83 +254,82 @@
!FIXME! Remark, difference between PARAMETER OPTIONS and COMMAND OPTIONS
-=item B<-r>, B<--raw>
+=nada
-Control whether the output controlled by the options B<--config>,
-B<--help>, B<--version> and B<--verbose> are raw text or annotated with
-terminal control sequences for better readability. By default B<rc>
-automatically determines whether F<stdout> is connected to a terminal or
-not and uses terminal sequences in the output or respectively raw text
-output only.
+=over 4
=item B<-v>, B<--verbose>
+ verbosely report processing, including all warnings
-Enables verbose messages on F<stdout>.
-
-=item B<-D>, B<--debug>
-
-Enables debugging messages on F<stderr>.
-
-!FIXME! Remark, difference between PARAMETER OPTIONS and COMMAND OPTIONS
-
-These options are mutually exclusive, i.e., you can specify only a
-single one to select the type of operation.
+=item B<-s>, B<--silent>
+ hold silence, and output no text messages whatsoever
-=over 4
+=item B<-d>, B<--debug>
+ don't remove any temporary files, and output debug messages
-=item B<-x>, B<--exec>
+As expected, when B<rc> has output it will write ASCII text to F<stdout> for
+normal output, and F<stderr> for abnormal output (such as warnings and
+errors.) The options for controlling the output content are B<--config>,
+B<--help>, B<--version>, B<--verbose>, and B<--silent>.
+
+The option B<-r> or B<--raw> turns on raw output mode. In this case, no
+formatting is done to output text. This mode contrasts formatted output mode,
+in which the output is annotated with terminal control sequences for better
+readability. This option has no single default value. If the raw mode option
+is not specified, B<rc> will determine whether F<stdout> is connected to a
+terminal. If so, B<rc> will run in formatted output mode. If F<stdout> is not
+connected to a terminal (such as with most daemons,) B<rc> will run in raw
+output mode even though it was not specified as an option.
-This is the default where all run-commands are executed in sub-shells.
-It expects exactly two non-option command line arguments: a I<package>
-name and a I<command> name.
+=item B<-c>, B<--config>
+ locate the configuration file in the following path,
+ overriding the environment variable $OSSP_RC_ROOT when
+ locating the configuration file
=item B<-p>, B<--print>
-
-Instead of (by default) executing the run-commands, print them to
-F<stdout> only.
+ output the text as it would be interpreted
+ by the shell, but do not run the commands
=item B<-e>, B<--eval>
-Instead of (by default) executing the run-commands in a sub-shell,
-return a command suitable for evaluation the run-commands in the
-current shell. Do not intermix this with option B<--print>, because
-B<--eval> prepares the run-commands in a temporary file and just
-outputs the necessary run and cleanup commands on F<stdout>. This is
-because most Bourne-Shell flavors dislike to C<eval> commands spanning
-multiple lines. So, B<--print> is for human readability and batch
-post-processing, while B<--eval> is for batch evaluation through the
-Bourne-Shell C<eval> command.
+The run command will not be executed. Rather, B<rc> will print a command
+suitable for later evaluation in the current shell. Given alone, this option
+will cause B<rc> to not execute the run command. Used together with B<--exec>,
+B<rc> will execute the run command and print a similar command for later
+execution as well. The B<--eval> option cannot be used together with
+B<--print>, because of conflicting output and the way that B<rc> constructs
+the evaluation text. Specifically, most Bourne shells and derivatives report
+errors with commands spanning multiple lines.
+
+Consider using the B<--eval> option for batch evaluation with the Bourne shell
+C<eval> command. Use the B<--print> option for better human readability. See
+`EXAMPLES' for an example.
-This is usually used from within F<.profile> files to import the shell
-environment of the packages of an B<OpenPKG> hierarchy:
-
- $ eval `@l_prefix@/etc/rc --eval all env`
-
-=item B<-q>, B<--query>
+=item B<-x>, B<--exec>
-Query the current (still default or overridden) value of one or more
-run-command configuration variables (see rc-file section C<%config>).
-It expects exactly one non-option command line argument: a I<format>
-string. This is an arbitrary text string which can contain one or more
-B<OSSP var> variable specifications ("C<${>I<name>C<}>" in its simplest
-form).
+Exec is the most common option of all, in which B<rc> executes a run command
+made up of a given program and section. Options controlling the flow of
+execution include B<--print>, B<--eval>, and B<--exec>. When no option is given,
+B<rc> will default to B<--exec> and execute the run command directly.
+
+=item B<-q>, B<--query>
+
+Query the value of one or more configuration variables. These variables are
+set in the C<%config> section of the F<\<program\>.rc> file corresponding to a
+program. The B<--query> option may report a different value, however. It is
+possible for variable declarations in the F<rc.conf> file to override those in
+the program's own rc file. Used with the B<--query> option, B<rc> will expect
+exactly one command line argument to follow. This must be a I<format> string
+containing arbitrary text and optionally one or more B<OSSP var> variable
+specifications ("C<${>I<name>C<}>" in its simplest form.)
-=item B<-c>, B<--config>
+=item B<-l>, B<--labels>
+ learn what section labels a run command extends
=item B<-i>, B<--info>
+ print a comprehensive summary of the rc environment
-Prints a summary of the whole run-command environment of B<rc>
-and exits immediately.
-
-=item B<-h>, B<--help>
-
-Prints the B<rc> usage information and exits immediately.
-
-=item B<-V>, B<--version>
-
-Prints the B<rc> version and copyright information and exits immediately.
-
-=back
+=back 4
=head1 WARNINGS
@@ -317,8 +337,6 @@
=over 4
-An explanation of all possible exit status values
-
The exit status is 0 if rc was able to initiate the given section code of the
given run command(s). If rc encountered an error during its processing, the
exit status is indexed to the first command parameter which failed as ordered
|
