Index: ossp-pkg/rc/rc.pod RCS File: /v/ossp/cvs/ossp-pkg/rc/rc.pod,v rcsdiff -q -kk '-r1.4' '-r1.5' -u '/v/ossp/cvs/ossp-pkg/rc/rc.pod,v' 2>/dev/null --- 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]
[
...] +=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. 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
+ +-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 @@ -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. 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 @@ -155,6 +231,8 @@ tries to use (in this order) C<$TMPDIR>, C<$TEMPDIR>, C<~/tmp> and C. +!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. -=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