OSSP CVS Repository

ossp - ossp-pkg/rc/rc.pod 1.8
Not logged in
[Honeypot]  [Browse]  [Directory]  [Home]  [Login
[Reports]  [Search]  [Ticket]  [Timeline
  [Raw

ossp-pkg/rc/rc.pod 1.8
##
##  rc.pod -- OSSP Run Command Facility (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>
##
##  Permission to use, copy, modify, and distribute this software for
##  any purpose with or without fee is hereby granted, provided that
##  the above copyright notice and this permission notice appear in all
##  copies.
##
##  THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
##  WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
##  MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
##  IN NO EVENT SHALL THE AUTHORS AND COPYRIGHT HOLDERS AND THEIR
##  CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
##  SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
##  LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
##  USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
##  ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
##  OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
##  OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
##  SUCH DAMAGE.
##

=pod

=head1 NAME

=over 4

B<rc> - OSSP Run Command Facility

=back 4

=head1 SYNOPSIS

=over 4

rc [-h|--help] [-V|--version] [-v|--verbose]
   [-d|--debug] [-p|--print] [-e|--eval]
   [-c|--config] [-q|--query] [-r|--raw]
   <command> <section> [<section> ...]

=back 4

=head1 DESCRIPTION

=over 4

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.<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.'

=back 4

=head1 OPTIONS

=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 $OSSP_RC_ROOT

=item B<-n>, B<--func> F<file>[C<:>F<file>[...]]
specify the location of an optional functions file,
containing Bourne shell script code

=item B<-f>, B<--file> F<file>
use the configuration and section data of a particular file

=item B<-d>, B<--dirs> I<dir>[C<:>I<dir>[...]
override OSSP_RC_ROOT, and use these paths instead

=item B<-t>, B<--tmpdir> I<dir>
specify the location of the temporary directory

=item B<-v>, B<--verbose>
verbosely report processing, including all warnings

=item B<-s>, B<--silent>
hold silence, and output no text messages whatsoever

=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

Mutually exclusive options, i.e. only a single one can be given

=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), follow with <program> <section>

=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

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 RETURN VALUE

=over 4

Returns zero if successful, or nonzero if otherwise.

=back 4

=head1 ERRORS

=over 4

-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.'

=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<eval>
command. This is often seen when importing the environment of packages of an
B<OpenPKG> hierarchy.

 $ eval `@l_prefix@/etc/rc --eval all env`

=item B<General>

@l_prefix@/etc/rc
[B<-f>|B<--rcfile> I<file>] 
[B<-d>|B<--rcdir> I<dir>[C<:>I<dir>[...]] 
[B<-C>|B<--rcconf> I<file>[C<:>I<file>[...]]] 
[B<-F>|B<--rcfunc> I<file>[C<:>I<file>[...]]] 
[B<-t>|B<--tmpdir> I<dir>]
[B<-r>|B<--raw>]
[B<-v>|B<--verbose>] 
[B<-D>|B<--debug>] 
[I<command-options>]
[I<command-arguments>]

=item B<Run-Command Execution>

@l_prefix@/etc/rc
[I<parameter-options>]
[B<-x>|B<--exec>] 
[B<-p>|B<--print>] 
[B<-e>|B<--eval>] 
I<package> 
I<command>

=item B<Configuration Query>

@l_prefix@/etc/rc
[I<parameter-options>]
[B<-q>|B<--query>] 
I<format>

@l_prefix@/etc/rc
[I<parameter-options>]
[B<-c>|B<--config>] 
[I<package>]

=item B<Facility Query>

@l_prefix@/etc/rc
[I<parameter-options>]
[B<-i>|B<--info>] 

@l_prefix@/etc/rc
[B<-h>|B<--help>]
[B<-V>|B<--version>]

=back 4

=head1 ENVIRONMENT

=over 4

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.

=back 4

=head1 FILES

=over 4

/$OSSP_RC_ROOT/rc.conf      - Configuration file

=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.

biff(1), bagg(1), honk(1), gonk(1), and quatch(1).

=back 4

=head1 NOTES

=over 4

# ref: %start; %stop
# cfg 
#     --glob-rcfile='rc.%s' 
#     --regex-section='(?<=^|\n)%%%s\s*\n(.+?)(?=\n%\S+|$)'
#     --regex-reference='(?<=^|\n)%%%s\s*(.+?)(?=\n|;)'
# def --showdefault, --defsetion=config

!FIXME! Remark, difference between PARAMETER OPTIONS and COMMAND OPTIONS

=over 4

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>.

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. 

=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.)

=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.

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
`EXAMPLES' for an example.

=item B<-x>, B<--exec>

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.

=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.)

=back 4

=head1 WARNINGS

=over 4

There are no warnings. OSSP rc is perfect ;-)

=back 4

=head1 DIAGNOSTICS

=over 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 BUGS

=over 4

!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.

=back 4

=head1 RESTRICTIONS

=over 4

Bugs we don't plan to fix include washing out the bathtub. !FIXME!

=back 4

=head1 AUTHORS

=over 4

Ralf S. Engelschall
Michael Schloh von Bennewitz

=back 4

=head1 HISTORY

=over 4

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.

=back 4

=cut

CVSTrac 2.0.1