[

...] =item B @l_prefix@/etc/rc [B<-f>|B<--rcfile> I] [B<-d>|B<--rcdir> I[C<:>I[...]] [B<-C>|B<--rcconf> I[C<:>I[...]]] [B<-F>|B<--rcfunc> I[C<:>I[...]]] [B<-t>|B<--tmpdir> I] [B<-r>|B<--raw>] [B<-v>|B<--verbose>] [B<-D>|B<--debug>] [I] [I] [I] =item B @l_prefix@/etc/rc [I] [B<-x>|B<--exec>] [B<-p>|B<--print>] [B<-e>|B<--eval>] I I [I ...] =item B @l_prefix@/etc/rc [I] [B<-q>|B<--query>] I @l_prefix@/etc/rc [I] [B<-c>|B<--config>] [I] =item B @l_prefix@/etc/rc [I] [B<-i>|B<--info>] @l_prefix@/etc/rc [B<-h>|B<--help>] [B<-V>|B<--version>] =back 4 =head1 DESCRIPTION =over 4 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 =head1 OPTIONS =over 4 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 $OSSP_RC_CONFIG and the built-in hard-coded value (see DEFAULTS.)!FIXME! =item B<-n>, B<--func> F[C<:>F[...]] specify the location of an optional functions file, containing Bourne shell script code =item B<-f>, B<--file> F use the configuration and section data of a particular file =item B<-d>, B<--dirs> I[C<:>I[...] override OSSP_RC_DIRS, and use these paths 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 =item B<-d>, B<--debug> don't remove temporary files, and output debug messages to stderr =item B<-r>, B<--raw> 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 =item B<-V>, B<--version> print version and copyright, then exit =item B<-p>, B<--print> output the text as it would be interpreted by the shell, but do not run the commands =item B<-e>, B<--eval> output the text for a command suitable for shell evaluation =item B<-x>, B<--exec> execute in subshell(s), will actually run the commands =item B<-q>, B<--query> print the value(s) of rc configuration variables =item B<-l>, B<--labels> learn what section labels a run command offers =item B<-i>, B<--info> print a comprehensive summary of the rc environment =back 4 =head1 NOTES =over 4 =item B<-h>, B<--help>, B<-V>, B<--version>, B<-v>, B<--verbose>, and B<-q> B<--silent> 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. =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 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 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> 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> 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 DEFAULT VALUES =over 4 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> 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 RETURN VALUE =over 4 -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 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 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 - Postprocess variable declaration file F> - Run command file =back 4 =back 4 =head1 SEE ALSO =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 =over 4 Ralf S. Engelschall Michael Schloh von Bennewitz =back 4 =head1 HISTORY =over 4 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