--- 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 <http://www.ossp.org/>
## Copyright (c) 2000-2002 Ralf S. Engelschall <rse@engelschall.com>
@@ -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 <class>[,<class>[,...]] <cmd> [-<opt> ...] [<cmd> ...]
-
-# 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";
-
-<!-- rc.foo -->
-<config>
- <set name=foo>1</set>
- <set name=bar>2</set>
-</config>
-<start user=root priority=20>
- /cw/bin/fooctl start $foo
-</start>
-<stop user=root priority=200>
- /cw/bin/fooctl stop $bar
-</stop>
-<restart user=root>
- %stop
- sleep 1
- %start
-</restart>
-<foo command=/usr/bin/perl>
- print STDERR "foo";
-</foo>
-
-rc <package> <section> [<section> ...]
-
-foreach sec in <section> [<section> ...] {
- foreach dir in --dir=dir1:dir2:.. {
- search for --rcfile where %s is <package>
- parse rcfile into blocks according to --regex-section/etc.
- remember common/<section> into list
- }
- // we now have an unsorted list of common/<section>
- sort list of common/<section> according to their priority (see --regex-param)
-
- // execution
- forearch common/<section> 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<rc> - OSSP Run Command Facility
+B<rc> - 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]
+# <command> <section> [<section> ...]
+
=item B<General>
@l_prefix@/etc/rc
@@ -194,19 +96,34 @@
=over 4
-B<OSSP rc> 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.<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.'
+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.<program> including script code grouped into sections. To
+help understand this file structure and how a section typically looks, an
+example called F<rc.example> 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<program> 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<file>
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<file>[C<:>F<file>[...]]
@@ -235,7 +150,7 @@
=item B<-d>, B<--dirs> I<dir>[C<:>I<dir>[...]
-override OSSP_RC_ROOT, and use these paths instead
+override OSSP_RC_DIRS, and use these paths instead
=item B<-t>, B<--tmpdir> I<dir>
@@ -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 <program> <section>
+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<rc>, but control the general output of all
+script code found in the F<rc.files> as well. For example, specifying
+B<--silent> will mute B<rc>'s output and also all script output that B<rc>
+runs.
-As expected, when B<rc> has output it will write ASCII text to F<stdout> for
-normal output, and F<stderr> 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<dir>
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<rc> will determine whether F<stdout> is connected to a
-terminal. If so, B<rc> will run in formatted output mode. If F<stdout> is not
-connected to a terminal (such as with most daemons,) B<rc> 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<dir>
-Specifying this option will force B<rc> to use the given temporary directory
-I<dir> for all its temporary output. If this option is not given, B<rc> will
-try to use C<$TMPDIR>, C<$TEMPDIR>, C<~/tmp> and C</tmp> (in that order.)
+Specifying the option B<--tmpdir> will force B<rc> to use the given temporary
+directory I<dir> for all its temporary output.
=item B<-e>, B<--eval> and B<-p>, B<--print>
-The run command will not be executed. Rather, B<rc> will print a command
-suitable for later evaluation in the current shell. Given alone, this option
-will cause B<rc> to not execute the run command. Used together with B<--exec>,
-B<rc> 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<rc> 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<rc> will print a command suitable for later evaluation in
+the current shell. Given alone, this option will cause B<rc> to not execute
+the run command. Used together with B<--exec>, B<rc> 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<rc> 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<eval> 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<rc> executes a run command
+The B<--exec> is the most common option of all, in which B<rc> 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<rc> 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<\<program\>.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<rc.conf> file to override those in
-the program's own rc file. Used with the B<--query> option, B<rc> will expect
-exactly one command line argument to follow. This must be a I<format> string
-containing arbitrary text and optionally one or more B<OSSP var> variable
-specifications ("C<${>I<name>C<}>" in its simplest form.)
+The B<--query> option queries the I<effective> value of one or more
+configuration variables. These variables are set in the C<%config> section of
+the corresponding F<rc.\<program\>> file. The B<--query> option reports the
+I<effective> value, and not necessarily that written in the F<rc.\<program\>>
+file, which can be overridden by variable settings in the F<rc.config> file.
+
+Used with the B<--query> option, B<rc> will expect exactly one command line
+argument to follow. This must be a I<format> string containing arbitrary text
+and optionally one or more B<OSSP var> variable specifications
+("C<${>I<name>C<}>" 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<OSSP rc>, all options have a reasonable default value. This allows for a
+configurationless B<rc> installation.
+
+=item B<-r>, B<--raw>
+
+The B<--raw> option determines its default at runtime. If the raw mode option
+is not specified, B<rc> will determine whether F<stdout> is connected to a
+terminal. If so, B<rc> will run in formatted output mode. If F<stdout> is not
+connected to a terminal (such as with most daemons,) B<rc> will run in raw
+output mode even though it was not specified as an option.
+
+=item B<-t>, B<--tmpdir> I<dir>
+
+If the B<--dirs> option is not given, B<rc> will try to use C<$TMPDIR>,
+C<$TEMPDIR>, C<~/tmp> and C</tmp> (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<rc> will default to
+B<--exec>.
+
+=item B<-c>, B<--config> F<file>
+=item B<-n>, B<--func> F<file>[C<:>F<file>[...]]
+=item B<-f>, B<--file> F<file>
+=item B<-d>, B<--dirs> I<dir>[C<:>I<dir>[...]
+
+#!FIXME! Sprech mal von Pfad und Dateien defaults wieviel rc.conf erlaubt
+#!FIXME! sind, und welche genommen wird oder sonst wie gemerged.
+
+F<rc.conf>
+F<rc.func>
+F<rc.config>
+F<rc.\<program\>>
+
+#!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<rc.conf> file.
+OSSP_RC_DIRS - Where to find the F<rc.\<program\>> 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<rc's> 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<OpenPKG> 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<rc.conf> - Master configuration file
+
+The following filenames are specified in F<rc.conf>. Both their names and
+locations may be different due to user customizations.
+
+=over 4
+
+F<rc.func> - User defined functions file
+F<rc.config> - Postprocess variable declaration file
+F<rc.\<program\>> - Run command file
+
+=back 4
+
+=back 4
=head1 SEE ALSO
-B<OSSP rc> 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 <rse@engelschall.com>
- Michael Schloh von Bennewitz <michael.schloh@cw.com>
+=over 4
+
+Ralf S. Engelschall
+
+Michael Schloh von Bennewitz
+
+=back 4
=head1 HISTORY
-B<OSSP rc> 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<OSSP rc> is intended to
-replace it with a faster, more robust and flexible facility.
+=over 4
-=cut
+B<OSSP rc> 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<OSSP rc> is intended to faster, more robust, and
+more flexible. This flexibility allows for wider range of use, however. B<OSSP
+rc> can therefore be used in a variety of situations, and is no longer
+exclusive to the OpenPKG project.
+=back 4
+
+=cut
|
