--- rc.pod 2002/01/18 16:47:53 1.4
+++ rc.pod 2002/01/21 18:14:54 1.5
@@ -43,6 +43,130 @@
[-c|--config] [-q|--query] [-r|--raw]
<command> <section> [<section> ...]
+=head1 DESCRIPTION
+
+OSSP rc is a run command processor. It applies the script code associated with
+a given section label to one or more given commands. The command(s) must each
+have entries in the form rc.<command> including script code grouped into
+sections. OSSP rc references these command entries by reading the
+configuration file (see FILES) and searching the directory where the command
+entries reside.
+
+Each section of script code extends a type of functionality described by its
+section label. This label is the same one given before the desired command(s).
+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.)
+
+=head1 OPTIONS
+
+Inclusive options which may be used with another
+
+-v, --verbose
+ verbosely report processing, including all warnings
+
+-s, --silent
+ hold silence, and output no text messages whatsoever
+
+-d, --debug
+ don't remove any temporary files, and output debug messages
+
+-r, --raw
+ output text using no terminal control sequences
+
+Mutually exclusive options, i.e. only a single one can be given
+
+-h, --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
+
+-p, --print
+ output the text as it would be interpreted
+ by the shell, but do not run the commands
+
+-e, --eval
+ output the text for a command suitable for shell evaluation
+
+-x, --exec
+ execute in subshell(s), follow with <package> <section>
+
+-q, --query
+ print the value(s) of rc configuration variables
+
+-l, --labels
+ learn what section labels a run command extends
+
+-i, --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.
+
+=head1 RETURN VALUE
+
+Returns zero if successful, or nonzero if otherwise.
+
+=head1 ERRORS
+
+-1 Faulty run command hierarchy
+ 0 Success
+ 1 First (or only) run command failed
+ 2 Second run command failed
+ N Nth run command failed
+
+Positive error values are indexed to their respective run commands by command
+line ordering. For more information see `DIAGNOSTICS.'
+
+=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
+
+=head1 ENVIRONMENT
+
+OSSP_RC_ROOT - Where the OSSP rc hierarchy is located
+OSSP_RC_OPTIONS - Options, same as the command line ones
+
+The environment determines where rc will look before beginning to process run
+commands. It also influences the behaviour, just as the command line options
+do. There is no difference between typing an option in the command line, and
+adding the same option to the OSSP_RC_OPTIONS variable.
+
+OSSP_RC_IMPLS - Other rc implementations
+
+The OSSP_RC_IMPLS variable plays a role only when the user has more than one
+logical set of run command sections. If rc reads anything but EOL in this
+variable, it will assume that more than one rc implementation exists. The
+variable should contain a chain of paths where other rc implementations are.
+This allows the user to build several OSSP rc hierarchies and then switch from
+each... Blah FIXME I don't know if we should be paying attention to the
+ENVIRONMENT guys. Maybe this is not a good solution for our dynamic OpenPKG
+environment problem after all.
+
+=head1 FILES
+
+/$OSSP_RC_ROOT/rc.conf - Configuration file
+
+=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.
+
+biff(1), bagg(1), honk(1), gonk(1), and quatch(1).
+
+=head1 NOTES
+
=over 4
=item B<General>
@@ -91,54 +215,6 @@
[B<-h>|B<--help>]
[B<-V>|B<--version>]
-=head1 DESCRIPTION
-
-OSSP rc is a run command processor. It applies the script code associated with
-a given section label to one or more given commands. The command(s) must each
-have entries in the form rc.<command> including script code grouped into
-sections. OSSP rc references these command entries by reading the
-configuration file (see FILES) and searching the directory where the command
-entries reside.
-
-Each section of script code extends a type of functionality described by its
-section label. This label is the same one given before the desired command(s).
-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.)
-
-=head1 PARAMETER OPTIONS
-
--h, --help
- print this help, then exit
-
--V, --version
- print version number, then exit
-
--v, --verbose
- verbosely report processing, including all warnings
-
--d, --debug
- don't remove any temporary files
-
--p, --print
- print the name of each section as it is processed
-
--e, --eval
- evaluate the nature of a fat tomato sandwich FIXME!
-
--c, --config
- locate the configuration file in the following path
-
--q, --query
- ask Ralf what he thinks about snails FIXME!
-
--r, --raw
- the sushi is too raw, and must be cooked longer FIXME!
-
-All of these options have reasonable default values,
-which OSSP rc assumes when no option is given.
-
=over 4
=item B<-f>, B<--rcfile> I<file>
@@ -155,6 +231,8 @@
tries to use (in this order) C<$TMPDIR>, C<$TEMPDIR>, C<~/tmp> and
C</tmp>.
+!FIXME! Remark, difference between PARAMETER OPTIONS and COMMAND OPTIONS
+
=item B<-r>, B<--raw>
Control whether the output controlled by the options B<--config>,
@@ -172,9 +250,7 @@
Enables debugging messages on F<stderr>.
-=back4
-
-=head1 COMMAND OPTIONS
+!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.
@@ -235,57 +311,50 @@
=back
-=head1 RETURN VALUE
-
-Will return an error every single time ;-)
-
-=head1 EXAMPLES
-
-/myetc/rc start sshd
-/etc/rc close docview primary
-/sfw/etc/rc restart lmtp2nntp
-/cw/etc/rc restart apache
-
-=head1 ENVIRONMENT
-
-=head1 FILES
-
-rc.conf
-
-=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.
-
-biff(1), bagg(1), honk(1), gonk(1), and quatch(1).
-
-=head1 NOTES
-
=head1 WARNINGS
=head1 DIAGNOSTICS
-Rc will print out error messages to stderr. The messages can be used to
-diagnose possible sources of failure of the chosen command, or even within the
-run command structure itself. FIXME! Marcus Bemerkung. The possible errors
-observed include the following.
-
=over 4
-OSSP rc: The ice cream is too hot
-Possible solution: This error happens alot.
+An explanation of all possible exit status values
-OSSP rc: The hot chocolate has a fly in it
-Possible solution: Just take the fly out and drink the coffee.
+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
+by the command line. This means that if rc returns 3, the third run command
+given on the command line failed.
+
+FIXME! Choose one interpretation:
+1 This does not mean that only the third run command failed, however.
+ It is possible that the fourth and sixth failed as well, for example.
+
+2 Upon failure of any run command, OSSP rc halts and processes no more.
+ Because of such a failure, a long batch of run commands may not be processed.
+
+This may be important with long run command batches or dependencies between
+run commands, so plan well when constructing the order of run commands on the
+command line.
+
+In case rc fails when only one run command is given, the exit status will be 1
+as expected. If rc failed because of a broken run command hierarchy, the exit
+status will be -1. This can happen if a script file is moved or renamed, for
+example. If the run command hierarchy is broken, no further action is taken
+and no run commands are processed.
=back 4
=head1 BUGS
+!FIXME!
+To report a bug, please visit the web page http://www.ossp.org/bugdb.html. Be
+sure to include the word "rc" in the subject field of your bug report.
+
+OSSP rc contains no known bugs to date.
+
=head1 RESTRICTIONS
-Bugs we don't plan to fix include washing out the bathtub.
+Bugs we don't plan to fix include washing out the bathtub. !FIXME!
=head1 AUTHORS
@@ -294,6 +363,14 @@
=head1 HISTORY
-Part of the OpenPKG distribution. Had its start in OpenPKG development.
+OSSP rc was born to replace the run command logic used in the OpenPKG project.
+In the first version of OpenPKG (http://www.openpkg.org), a run command script
+called `rc' could issue run commands to programs installed under the OpenPKG
+software hierarchy. This solution had a number of inconveniences, however. As
+time wore on, developers at Cable & Wireless Deutschland GmbH decided to
+replace the bourne shell script with a faster, more robust implementation.
+This is OSSP rc. By the way, an unplanned advantage of this redevelopment is
+that OSSP rc can be used for any project needing generic run command logic as
+well as the OpenPKG project as first planned.
=cut
|
