Index: ossp-pkg/rc/rc.pod RCS File: /v/ossp/cvs/ossp-pkg/rc/rc.pod,v rcsdiff -q -kk '-r1.15' '-r1.16' -u '/v/ossp/cvs/ossp-pkg/rc/rc.pod,v' 2>/dev/null --- rc.pod 2002/01/23 15:36:05 1.15 +++ rc.pod 2002/01/28 12:08:13 1.16 @@ -1,5 +1,5 @@ ## -## rc.pod -- OSSP Run Command Facility (Manual Page) +## rc.pod -- OSSP Run Command Processor (Manual Page) ## Copyright (c) 2000-2002 Cable & Wireless Deutschland GmbH ## Copyright (c) 2000-2002 The OSSP Project ## Copyright (c) 2000-2002 Ralf S. Engelschall @@ -23,116 +23,13 @@ ## SUCH DAMAGE. ## -# ref: %start; %stop -# cfg -# def --showdefault, --defsetion=config - -# --dir=dir1:dir2:.. -# --rcfile='rc.%s' -# --regex-section='(?<=^|\n)%%%s\s*\n(.+?)(?=\n%\S+|$)' -# --regex-param='..' -# --regex-reference='(?<=^|\n)%%%s\s*(.+?)(?=\n|;)' -# --regex-config='(\s+)=(.*)$' -# --name-config=config -# --name-common=common - -# RegexSection (?<=^|\n)%%%s\s*\n(.+?)(?=\n%\S+|$) - -# - instead of separate run-commands use a global one -# - temporarily deactivation of run-commands through environment variable -# - perhaps: "rc [,[,...]] [- ...] [ ...] - -# Examples: - -# rc.foo -%config - foo=1 - bar=2 -%start -u root -p 200 - /cw/bin/fooctl start $foo -%stop -u root -p 200 - /cw/bin/fooctl stop $bar -%restart -u root - %stop - sleep 1 - %start -%foo -c /usr/bin/perl - print STDERR "foo"; - - - - 1 - 2 - - - /cw/bin/fooctl start $foo - - - /cw/bin/fooctl stop $bar - - - %stop - sleep 1 - %start - - - print STDERR "foo"; - - -rc
[
...] - -foreach sec in
[
...] { - foreach dir in --dir=dir1:dir2:.. { - search for --rcfile where %s is - parse rcfile into blocks according to --regex-section/etc. - remember common/
into list - } - // we now have an unsorted list of common/
- sort list of common/
according to their priority (see --regex-param) - - // execution - forearch common/
in list { - prepend config section - prepend common section - expand references accordingf to --regex-reference - execute result as user/group (see --regex-param) with interpreter (see --regex-param) - } -} - -cd () { - eval `rc --eval --rcfunc=$HOME/.cdfunc --rcfile-owner=$USER --rcfile-umask=022 --dir .:..:../..:../../.. --rcfile .cd all leave` - builtin cd ${1+"$@"} - eval `rc --eval --rcfunc=$HOME/.cdfunc --rcfile-owner=$USER --rcfile-umask=022 --dir .:..:../..:../../.. --rcfile .cd all enter` -} - -# $HOME/.cdfunc -AddPath () { - ... -} -RemPath () { - ... -} - -# .cd -%enter - FOO=1 - export FOO - AddPath `pwd`/bin -%leave - unset FOO - RemPath `pwd`/bin - -TODO: -- error semantic: imediate faulure or skip failured -- security => --rcfile-umask - =pod =head1 NAME =over 4 -B - OSSP Run Command Facility +B - OSSP Run Command Processor =back 4 @@ -140,6 +37,11 @@ =over 4 +#rc [-h|--help] [-V|--version] [-v|--verbose] +# [-d|--debug] [-p|--print] [-e|--eval] +# [-c|--config] [-q|--query] [-r|--raw] +#
[
...] + =item B @l_prefix@/etc/rc @@ -194,19 +96,34 @@ =over 4 -B is a generic 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.' +OSSP rc is a run command processor. It applies the script code associated with +one or more given section label to a given program. The program must have an +entry in the form rc. including script code grouped into sections. To +help understand this file structure and how a section typically looks, an +example called F is included in the distribution. OSSP rc +references these command entries by reading the configuration file (see FILES) +and searching the directory where the program entries reside. + +Each section of script code offers a type of functionality described by its +section label. This label is the same one given on the command line after the +desired program name. Only one program may be processed at a time, although +many sections can be sourced with the same call to rc. An example of this is +given in `EXAMPLES.' + +There exists one exception to this rule in which an rc keyword named `all' is +reserved to mean `all programs.' The user may thus give the `all' wildcard in +place of the C parameter to process the given sections of all +programs 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.' =back 4 @@ -214,15 +131,13 @@ =over 4 -!FIXME! Remark, difference between PARAMETER OPTIONS and COMMAND OPTIONS - Inclusive options which may be used with another =item B<-c>, B<--config> F specify the location of the configuration file, -overriding the environment variable C<$OSSP_RC_CONFIG> -and the built-in hard-coded value. +overriding the environment variable $OSSP_RC_CONFIG +and the built-in hard-coded value (see DEFAULTS.)!FIXME! =item B<-n>, B<--func> F[C<:>F[...]] @@ -235,7 +150,7 @@ =item B<-d>, B<--dirs> I[C<:>I[...] -override OSSP_RC_ROOT, and use these paths instead +override OSSP_RC_DIRS, and use these paths instead =item B<-t>, B<--tmpdir> I @@ -247,7 +162,7 @@ =item B<-s>, B<--silent> -hold silence, and output no text messages whatsoever +be silent, and disable output =item B<-d>, B<--debug> @@ -257,8 +172,12 @@ output text using no terminal control sequences +=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 @@ -278,7 +197,7 @@ =item B<-x>, B<--exec> -execute in subshell(s), follow with
+execute in subshell(s), will actually run the commands =item B<-q>, B<--query> @@ -292,50 +211,44 @@ 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. For details of some listed option see -`NOTES'. - =back 4 =head1 NOTES =over 4 -!FIXME! Remark, difference between PARAMETER OPTIONS and COMMAND OPTIONS +=item B<-h>, B<--help>, B<-V>, B<--version>, B<-v>, B<--verbose>, and B<-q> +B<--silent> -=over 4 +The B<--help>, B<--version>, B<--verbose>, and B<--silent> options are used to +control the screen output of B, but control the general output of all +script code found in the F as well. For example, specifying +B<--silent> will mute B's output and also all script output that B +runs. -As expected, when B has output it will write ASCII text to F for -normal output, and F 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>. +=item B<-t>, B<--tmpdir> I 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 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. +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<--tmpdir> I -Specifying this option will force B to use the given temporary directory -I for all its temporary output. If this option is not given, B will -try to use C<$TMPDIR>, C<$TEMPDIR>, C<~/tmp> and C (in that order.) +Specifying the option B<--tmpdir> 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> -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. +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 @@ -343,59 +256,115 @@ =item B<-x>, B<--exec> -Exec is the most common option of all, in which B executes a run command +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>. When no option is given, -B will default to B<--exec> and execute the run command directly. +execution include B<--print>, B<--eval>, and B<--exec>. =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<\.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 file to override those in -the program's own rc 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.) +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> file. 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! =back 4 -=head1 ENVIRONMENT +=head1 DEFAULT VALUES =over 4 -OSSP_RC_ROOT - Where the OSSP rc hierarchy is located -OSSP_RC_OPTIONS - Options, same as the command line ones +In B, all options have a reasonable default value. This allows for a +configurationless B installation. + +=item B<-r>, B<--raw> + +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<-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.) + +=item B<-p>, B<--print>, B<-e>, B<--eval>, B<-x>, B<--exec> -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. +If neither B<--print>, B<--eval>, or B<­-exec> is given B will default to +B<--exec>. + +=item B<-c>, B<--config> F +=item B<-n>, B<--func> F[C<:>F[...]] +=item B<-f>, B<--file> F +=item B<-d>, B<--dirs> I[C<:>I[...] + +#!FIXME! Sprech mal von Pfad und Dateien defaults wieviel rc.conf erlaubt +#!FIXME! sind, und welche genommen wird oder sonst wie gemerged. + +F +F +F +F> + +#!FIXME! Kein mehr defaults, und sag so +=item B<-v>, B<--verbose> +=item B<-q>, B<--silent> +=item B<-d>, B<--debug> +=item B<-h>, B<--help> +=item B<-V>, B<--version> +=item B<-q>, B<--query> +=item B<-l>, B<--labels> +=item B<-i>, B<--info> + +=head1 ENVIRONMENT + +=over 4 + +OSSP_RC_CONFIG - Where to find the F file. +OSSP_RC_DIRS - Where to find the F> files. +OSSP_RC_OPTIONS - Options, same as the command line ones + +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_OPTIONS 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 FILES +=head1 RETURN VALUE =over 4 -/$OSSP_RC_ROOT/rc.conf - Configuration file +-1 Faulty run command hierarchy + 0 Success + 1 One or more run commands failed =back 4 =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 @@ -415,50 +384,84 @@ command. This is often seen when importing the environment of packages of an B hierarchy. - $ eval `@l_prefix@/etc/rc --eval all env` +=over 4 + +$ eval `@l_prefix@/etc/rc --eval all env` -=head1 DIAGNOSTICS +=back 4 -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 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 - Postprocess variable declaration file +F> - Run command file + +=back 4 + +=back 4 =head1 SEE ALSO -B integrates concepts taken from other run-command -architectures. For more information, inspect the /etc/rc facilities -provided by FreeBSD, NetBSD and Solaris. +=over 4 + +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. + +rc.conf(1), rc.func(1), rc.config(1), rc.program(1), and rc-sample(1). + +=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 - Ralf S. Engelschall - Michael Schloh von Bennewitz +=over 4 + +Ralf S. Engelschall + +Michael Schloh von Bennewitz + +=back 4 =head1 HISTORY -B was born to replace 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 is intended to -replace it with a faster, more robust and flexible facility. +=over 4 -=cut +B 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 is intended to faster, more robust, and +more flexible. This flexibility allows for wider range of use, however. B can therefore be used in a variety of situations, and is no longer +exclusive to the OpenPKG project. +=back 4 + +=cut