##
## rc.pod -- OpenPKG Run-Command Facility (Manual Page)
## Copyright (c) 2000-2002 Cable & Wireless Deutschland GmbH
## Copyright (c) 2000-2002 The OpenPKG Project
## Copyright (c) 2000-2002 Ralf S. Engelschall
##
## 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
B - OpenPKG Run-Command Facility
=head1 SYNOPSIS
=over 4
=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]
=item B
@l_prefix@/etc/rc
[I]
[B<-x>|B<--exec>]
[B<-p>|B<--print>]
[B<-e>|B<--eval>]
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>]
=head1 PARAMETER OPTIONS
All these options have reasonable builtin defaults by can be used to
adjust one or more parameters of the B facility.
=over 4
=item B<-f>, B<--rcfile> I
=item B<-d>, B<--rcdir> I[C<:>I[...]
=item B<-C>, B<--rcconf> I[C<:>I[...]]
=item B<-F>, B<--rcfunc> I[C<:>I[...]]
=item B<-t>, B<--tmpdir> I
Force the use of a particular temporary directory. By default B
tries to use (in this order) C<$TMPDIR>, C<$TEMPDIR>, C<~/tmp> and
C.
=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
automatically determines whether F 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.
=item B<-D>, B<--debug>
Enables debugging messages on F.
=back4
=head1 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
name and a I name.
=item B<-p>, B<--print>
Instead of (by default) executing the run-commands, print them to
F 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. This is
because most Bourne-Shell flavors dislike to C 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 command.
This is usually used from within F<.profile> files to import the shell
environment of the packages of an B 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
string. This is an arbitrary text string which can contain one or more
B variable specifications ("C<${>IC<}>" 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
and exits immediately.
=item B<-h>, B<--help>
Prints the B usage information and exits immediately.
=item B<-V>, B<--version>
Prints the B version and copyright information and exits immediately.
=back
=cut