##
##  rc.pod -- OpenPKG Run-Command Facility (Manual Page)
##  Copyright (c) 2000-2002 Cable & Wireless Deutschland GmbH
##  Copyright (c) 2000-2002 The OpenPKG Project <http://www.openpkg.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.
##

# 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

=pod

=head1 NAME

B<rc> - OpenPKG Run-Command Facility

=head1 SYNOPSIS

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

=head1 DESCRIPTION

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

=head1 OPTIONS

Inclusive options which may be used with another

-v, --verbose
        verbosely report processing, including all warnings

-s, --silent
        hold silence, and output no text messages whatsoever

-d, --debug
        don't remove any temporary files, and output debug messages

-r, --raw
        output text using no terminal control sequences

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

-h, --help
        print this help, then exit

-V, --version
        print version number, then exit

-c, --config
        locate the configuration file in the following path,
        overriding the environment variable $OSSP_RC_ROOT when
        locating the configuration file

-p, --print
        output the text as it would be interpreted
        by the shell, but do not run the commands

-e, --eval
        output the text for a command suitable for shell evaluation

-x, --exec
        execute in subshell(s), follow with <package> <section>

-q, --query
        print the value(s) of rc configuration variables

-l, --labels
        learn what section labels a run command extends

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

=head1 RETURN VALUE

Returns zero if successful, or nonzero if otherwise.

=head1 ERRORS

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

=head1 EXAMPLES

/myetc/rc start sshd
/etc/rc close docview primary httpd sshd radiusd
/sfw/etc/rc restart smtpd lmtp2nntp
/cw/etc/rc restart apache

=head1 ENVIRONMENT

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.

=head1 FILES

/$OSSP_RC_ROOT/rc.conf      - Configuration file

=head1 SEE ALSO

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

=head1 NOTES

=over 4

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

=over 4

=item B<-f>, B<--rcfile> I<file>

=item B<-d>, B<--rcdir> I<dir>[C<:>I<dir>[...]

=item B<-C>, B<--rcconf> I<file>[C<:>I<file>[...]] 

=item B<-F>, B<--rcfunc> I<file>[C<:>I<file>[...]]

=item B<-t>, B<--tmpdir> I<dir>

Force the use of a particular temporary directory. By default B<rc>
tries to use (in this order) C<$TMPDIR>, C<$TEMPDIR>, C<~/tmp> and
C</tmp>.

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

=item B<-r>, B<--raw>

Control whether the output controlled by the options B<--config>,
B<--help>, B<--version> and B<--verbose> are raw text or annotated with
terminal control sequences for better readability. By default B<rc>
automatically determines whether F<stdout> is connected to a terminal or
not and uses terminal sequences in the output or respectively raw text
output only.

=item B<-v>, B<--verbose>

Enables verbose messages on F<stdout>.

=item B<-D>, B<--debug>

Enables debugging messages on F<stderr>.

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

These options are mutually exclusive, i.e., you can specify only a
single one to select the type of operation.

=over 4

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

This is the default where all run-commands are executed in sub-shells.
It expects exactly two non-option command line arguments: a I<package>
name and a I<command> name.

=item B<-p>, B<--print>

Instead of (by default) executing the run-commands, print them to
F<stdout> only.

=item B<-e>, B<--eval>

Instead of (by default) executing the run-commands in a sub-shell,
return a command suitable for evaluation the run-commands in the
current shell. Do not intermix this with option B<--print>, because
B<--eval> prepares the run-commands in a temporary file and just
outputs the necessary run and cleanup commands on F<stdout>. This is
because most Bourne-Shell flavors dislike to C<eval> commands spanning
multiple lines. So, B<--print> is for human readability and batch
post-processing, while B<--eval> is for batch evaluation through the
Bourne-Shell C<eval> command.

This is usually used from within F<.profile> files to import the shell
environment of the packages of an B<OpenPKG> hierarchy:

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

=item B<-q>, B<--query> 

Query the current (still default or overridden) value of one or more
run-command configuration variables (see rc-file section C<%config>).
It expects exactly one non-option command line argument: a I<format>
string. This is an arbitrary text string which can contain one or more
B<OSSP var> variable specifications ("C<${>I<name>C<}>" in its simplest
form).

=item B<-c>, B<--config>

=item B<-i>, B<--info>

Prints a summary of the whole run-command environment of B<rc>
and exits immediately.

=item B<-h>, B<--help>

Prints the B<rc> usage information and exits immediately.

=item B<-V>, B<--version>

Prints the B<rc> version and copyright information and exits immediately.

=back

=head1 WARNINGS

=head1 DIAGNOSTICS

=over 4

An explanation of all possible exit status values

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

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

=head1 RESTRICTIONS

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

=head1 AUTHORS

Ralf S. Engelschall
Michael Schloh von Bennewitz

=head1 HISTORY

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.

=cut