Index: ossp-pkg/rc/rc.pod RCS File: /v/ossp/cvs/ossp-pkg/rc/rc.pod,v rcsdiff -q -kk '-r1.20' '-r1.21' -u '/v/ossp/cvs/ossp-pkg/rc/rc.pod,v' 2>/dev/null --- rc.pod 2002/01/29 07:31:11 1.20 +++ rc.pod 2002/01/29 08:42:20 1.21 @@ -1,7 +1,3 @@ --------------------------------------------------------------------------------- -DO NOT EDIT. MAJOR REWRITES JOINING OPTIONS, NOTES AND DEFAULTS IN PROGRESS. THL --------------------------------------------------------------------------------- - ## ## rc.pod -- OSSP Run Command Processor (Manual Page) ## Copyright (c) 2000-2002 Cable & Wireless Deutschland GmbH @@ -41,64 +37,27 @@ =over 4 -=item B - @l_prefix@/etc/rc -[B<-c>|B<--conf> I[C<:>I[...]]] -[B<-t>|B<--tmp> I] -[B<-r>|B<--raw>] -[B<-v>|B<--verbose>] +[B<-?>|B<--usage>] [B<-D>|B<--debug>] - -=item B - -@l_prefix@/etc/rc -[I] -[B<-x>|B<--exec>] -[B<-p>|B<--print>] -[B<-e>|B<--eval>] -[B<-d>|B<--dirs> I[C<:>I[...]] -[B<-f>|B<--func> I[C<:>I[...]]] [B<-F>|B<--force>] +[B<-V>|B<--version>] +[B<-c>|B<--conf> I[C<:>I[...]]] +[B<-d>|B<--dirs> I[C<:>I[...]]] +[B<-e>|B<--eval>] +[B<-f>|B<--func> I[C<:>I[...]]] +[B<-h>|B<--help>] +[B<-i>|B<--info>] +[B<-l>|B<--labels>] +[B<-p>|B<--print>] +[B<-q>|B<--query>] I +[B<-s>|B<--silent>] +[B<-r>|B<--raw>] +[B<-t>|B<--tmp> I] +[B<-v>|B<--verbose>] +[B<-x>|B<--exec>] I I
-[I
...] - -=item B - -@l_prefix@/etc/rc -[I] -B<-q>|B<--query> I -[B<-d>|B<--dirs> I[C<:>I[...]] -[B<-F>|B<--force>] -I - -=item B - -[I] -<-l>|<--labels> -[B<-d>|B<--dirs> I[C<:>I[...]] -[B<-F>|B<--force>] -I - -# FIXME Ralf, what's that? -# @l_prefix@/etc/rc -# [I] -# [B<-c>|B<--conf>] -# [I] - -=item B - -@l_prefix@/etc/rc -[I] -[B<-i>|B<--info>] - -=item B - -@l_prefix@/etc/rc -[B<-?>|B<--usage>] -[B<-h>|B<--help>] -[B<-V>|B<--version>] =back 4 @@ -106,272 +65,135 @@ =over 4 -OSSP rc is a run command processor. It's primary function is to scan F -script files for B
(s) identified by corresponding label(s) and run the -commands in the section(s). - -The run command processor can also only print the commands without executing -them or reformat them to C input. The F files contain variables -and the command processor has functionality to query their default, set and -effective values. - -To understand the structure and syntax of F script files, an example -called F is included in the distribution. The rc environment and -behaviour is very configurable, so the syntax may vary and not match exactly -the example provided. +OSSP rc is a run command processor. It's primary function is to scan +F script files for B
(s) and run the commands listed in the +section(s). + +The run command processor can alternatively print the commands in human +readable format or reformat them for shell C input without executing +them. The F files contain variables and the command processor has +functionality to query their default, set and effective values. + +The structure of the Fs is simple but the syntax is highly +configurable. A F is divided into B
s and each of them is +identified by a label build from the B
name. The distribution +contains various examples. With a single call to rc usually one F may be processed at, although -many sections can be given to source their corresponding commands, see -EXAMPLES below. - -There is one exception to this rule in which an rc keyword named `all' is -reserved to mean `all Fs.' The user may thus give the `all' wildcard -in place of the C parameter to process the commands from the given -sections of all Cs found. - -#THL! does "all stop start" mean "a stop stop, a start, b start" or " a stop, -#a start, b stop, b start"? -#Prioritaeten - -#Using the `all' wildcard may be risky in some cases, because successful -#performance then depends not only on the code written into each program's -#sections but also if every single program found has the named section label at -#all. For information about the rc exit status after such an operation see -#`DIAGNOSTICS.' +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 +meaning `all Fs.' =back 4 =head1 OPTIONS =over 4 +=item B<-?>|B<--usage> -Inclusive options which may be used with another - -=item B<-c>, B<--conf> F - -specify the location of the configuration file. - -=item B<-f>, B<--func> F[C<:>F[...]] - -specify the location of one or more optional function files, containing -commands which are prepended to the sections of their corresponding -Cs. - -=item B<-F>, B<--force> - -Disable ${OSSP_RC_PREFIX} and ${OSSP_RC_SUFFIX} expansion on F. -Disable searching for F. This mode assumes F is a filename. It -is automagically entered when the F matches the regex '^\.{0,2}/'. - -=item B<-d>, B<--dirs> I[C<:>I[...] - -override OSSP_RC_DIRS, and use these paths to search for Fs instead. - -=item B<-t>, B<--tmpdir> I - -specify the location of the temporary directory - -=item B<-v>, B<--verbose> - -verbosely report processing, including all warnings - -=item B<-s>, B<--silent> - -be silent, and disable output +print short usage summary, then exit. -=item B<-D>, B<--debug> +=item B<-D>|B<--debug> don't remove temporary files, and output debug messages to stderr -=item B<-r>, B<--raw> +=item B<-F>|B<--force> -output text using no terminal control sequences +Usually F is a fraction of a filename and the run command facility +prefixes this name with ${OSSP_RC_PREFIX} and appends ${OSSP_RC_SUFFIX} to it, +then searches the file in directories given using --dirs. If the initial +F matches the regex '^\.{0,2}/', --force is automagically assumed. -=back 4 - -Mutually exclusive options, i.e. only a single one can be given - -=over 4 - -=item B<-h>, B<--help> - -print this help, then exit - -=item B<-?>, B<--usage> - -print short usage summary, then exit. - -=item B<-V>, B<--version> +=item B<-V>|B<--version> print version and copyright, then exit -=item B<-p>, B<--print> +=item B<-c>|B<--conf> I[C<:>I[...]] -output the commands as they would by seen by the command interpreter, but do -not run them. +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. -=item B<-e>, B<--eval> +=item B<-d>|B<--dirs> I[C<:>I[...]] -output the text for a command suitable for shell evaluation, but do not run -it. +directories to search for Fs. -=item B<-x>, B<--exec> +=item B<-e>|B<--eval> -execute the command interpreter in a subprocess and actually run the commands. +output the commands text in a format suitable for shell evaluation, but do not run it. -=item B<-q>, B<--query> +=item B<-f>|B<--func> I[C<:>I[...]] -print the value(s) of rc configuration variables defined in the %config section. +specify the location of one or more optional function files. They act like +libraries, containing commands which are prepended to the sections of their +corresponding Cs just before execution. -=item B<-l>, B<--labels> +=item B<-h>|B<--help> -learn what section labels a F offers. +print this help, then exit -=item B<-i>, B<--info> +=item B<-i>|B<--info> print a comprehensive summary of the rc environment -=back 4 - -=head1 NOTES - -=over 4 +=item B<-l>|B<--labels> -=item B<-h>, B<--help>, B<-V>, B<--version>, B<-v>, B<--verbose>, and B<-q> -B<--silent> +learn what section labels a F offers. -The B<--help>, B<--version>, B<--verbose>, and B<--silent> options are used to -control the screen output of B and control the general output of all -sections found in the Fs as well. For example, specifying -B<--silent> will mute B's output and also all command output that B -runs. - -=item B<-r>, B<--raw> I - -The option B<-r> or B<--raw> turns on raw output mode. In this case, no -formatting is done to the screen output. This mode is different from formatted -output mode, in which the output is annotated with terminal control sequences -for better readability. - -=item B<-t>, B<--tmp> I - -Specifying this option will force B to use the given temporary -directory I for all its temporary output. - -=item B<-e>, B<--eval> and B<-p>, B<--print> - -With the B<--eval> or B<--print> options, the run command will not be -executed. Rather, B will print a command suitable for later evaluation in -the current shell. Given alone, this option will cause B to not execute -the run command. Used together with B<--exec>, B 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 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 command. Use the B<--print> option for better human readability. See -`EXAMPLES' for an example. - -=item B<-x>, B<--exec> - -The B<--exec> is the most common option of all, in which B 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>. - -=item B<-q>, B<--query> - -The B<--query> option queries the I value of one or more -configuration variables. These variables are set in the C<%config> section of -the corresponding F. The B<--query> option reports the -I value, and not necessarily that written in the F -file, which can be overridden by variable settings in the F file. - -Used with the B<--query> option, B will expect exactly one command line -argument to follow. This must be a I string containing arbitrary text -and optionally one or more B variable specifications -("C<${>IC<}>" in its simplest form.) -!FIXME what is var here! +=item B<-p>|B<--print> -=back 4 +output the commands text in a format suitable for human reading, but do not run it. -=head1 DEFAULT VALUES +=item B<-q>|B<--query> I -=over 4 +query the effective value of configuration variables from the %config section +and print them using the I string specified in RPM style. -In B, all options have a reasonable default value. This allows for a -configurationless B installation. +=item B<-r>|B<--raw> -=item B<-r>, B<--raw> +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 +runtime and is automagically disabled if stdout is detached from a terminal. -The B<--raw> option determines its default at runtime. If the raw mode option -is not specified, B will determine whether F is connected to a -terminal. If so, B will run in formatted output mode. If F is not -connected to a terminal (such as with most daemons,) B will run in raw -output mode even though it was not specified as an option. +=item B<-s>|B<--silent> -=item B<-t>, B<--tmpdir> I - -If the B<--dirs> option is not given, B will try to use C<$TMPDIR>, -C<$TEMPDIR>, C<~/tmp> and C (in that order.) +be silent, and disable output -=item B<-p>, B<--print>, B<-e>, B<--eval>, B<-x>, B<--exec> +=item B<-t>|B<--tmp> I -If neither B<--print>, B<--eval>, or B<­-exec> is given B will default to -B<--exec>. +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, in that +order. -=item B<-c>, B<--conf> F +=item B<-v>|B<--verbose> -Using F from command line option -c aka --conf, fallback to -${OSSP_RC_CONF}, fallback to "@l_prefix@/etc/rc.conf". +be verbose, output what's going on. -=item B<-f>, B<--func> F[C<:>F[...]] -=item B<-F>, B<--force> -=item B<-d>, B<--dirs> I[C<:>I[...] +=item B<-x>|B<--exec> -#!FIXME! Sprech mal von Pfad und Dateien defaults wieviel rc.conf erlaubt -#!FIXME! sind, und welche genommen wird oder sonst wie gemerged. +execute the command interpreter in a subprocess and actually run the commands. +If neither B<--print>, B<--eval>, or B<­-exec> is given, the default is +B<--exec> anyway. -F -F -F -F +=back 4 =head1 ENVIRONMENT =over 4 -Every command line longoption is also a keyword in the rc.conf file and, +Every command line longoption is also a keyword in the F file and, prefixed with "OSSP_RC_" and it's name in upper case, also available as an environment variable. -The environment determines where rc will search before beginning to process -run commands. It also influences B behaviour, just as the command line -options do. There is no difference between typing an option in the command -line, and appending the same option to the OSSP_RC_OPTS variable. - -#!FIXME! Study this and determine if it is needed -#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. - =back 4 =head1 RETURN VALUE =over 4 --1 Faulty run command hierarchy +-1 Error in rc 0 Success - 1 One or more run commands failed + 1 Error in command executed by rc =back 4 @@ -398,30 +220,14 @@ command. This is often seen when importing the environment of packages of an B hierarchy. -=over 4 - -$ eval `@l_prefix@/etc/rc --eval all env` - -=back 4 - -=back 4 - =head1 FILES =over 4 F - Master configuration file - -The following filenames are specified in F. Both their names and -locations may be different due to user customizations. - -=over 4 - -F - User defined functions file +F - User defined functions library F - Postprocess variable declaration file -F> - Run command file - -=back 4 +F - Run commands for "foo" application =back 4 @@ -437,24 +243,6 @@ =back 4 -=head1 DIAGNOSTICS - -=over 4 - -If rc fails while processing a run command, the exit status will be 1. If rc -failed due to a broken run command configuration, the exit status will be -1. -This can happen if a script file is moved or renamed, for example. If the run -command configuration is broken, no further action is taken and no run -commands are processed. - -Importantly, if the keyword `all' is given as the program wildcard parameter, -then processing will begin and continue until the first error is reached. -Should an error arise, processing will stop and the exit status will be 1. -There is no way to learn which command caused the error unless it is apparent -from the text output of the rc process. - -=back 4 - =head1 AUTHORS =over 4