=pod

=head1 NAME

rc-sample -- B<OSSP rc> Example Use Cases

=head1 DESCRIPTION

This documents typical use cases for B<OSSP rc>.

=head1 USE CASE: OpenPKG Run-Command Facility

This describes how B<OSSP rc> is used as the B<OpenPKG>
(http://www.openpkg.org/) run-command facility. First, the involved files:

=over 4

=item F</cw/etc/rc>

This is just the location of the B<OSSP rc> program.

=item F</cw/etc/rc.cf> 

This is the B<OSSP rc> configuration file, hard-coded into
F</cw/etc/rc> at configure/build time with the Autoconf option
C<--with-config=/cw/etc/rc.cf>. It is installed at B<OpenPKG>
bootstrap time and used read-only.

 Dirs          /cw/etc/rc.d:/cw/local/etc/rc.d
 Name          rc.%s/rc.*
 ConfigDef     (?<=^\s*)([a-zA-Z_][a-zA-Z_0-9]*)=("[^"]*"|'[^']*'|\S+)
 SectionDef    (?<=^|\n)%([a-zA-Z][a-zA-Z0-9]*)(\s+-[a-zA-Z]\s*\S+)\s*\n(.+?)(?=\n%%\S+|$)
 ParamDef      (?<=^|\s)-([a-zA-Z])\s*(\S+)
 SectionRef    (?<=^\s*|;\s*)%([a-zA-Z][a-zA-Z0-9]*)(\s+[^\n]+)?
 ParamRef      \$([0-9])
 NameConfig    config
 NameCommon    common
 Execute       root  %s
 Execute       !root sudo %s
 LineControl   yes

=item F</cw/etc/rc.func> (C<%common> extensions)

This is the B<OpenPKG> Bourne-Shell script providing a set of reusable
functions. It is installed at B<OpenPKG> bootstrap time and used
read-only.

 opVarIsYes () {
     _var="${1}"
     eval "_val=\"\$${_var}\""
     case "${_val}" in
         [Yy][Ee][Ss] | [Tt][Rr][Uu][Ee] | [Oo][Nn] | 1 )
             unset _var _val
             return 0
             ;;
         [Nn][Oo] | [Ff][Aa][Ll][Ss][Ee] | [Oo][Ff][Ff] | 0 )
             unset _var _val
             return 1
             ;;
         *)
             opWarn "variable \$${_var} is not set properly."
             unset _var _val
             return 1
         ;;
     esac
 }
 opServiceEnabled () {
     opVarIsYes ${1}_enable
 }

=item F</cw/etc/rc.conf> 

This is the B<OpenPKG> configuration script where the administrator
overrides the variables from the script's C<%config> sections. It it
generated (as an empty file) on B<OpenPKG> bootstrap time and manually
edited later to influence the behaviours of the package's run-command
scripts (here F</cw/etc/rc.d/rc.foo>).

 foo_enable=yes
 foo_flags="--sample"

=item F</cw/etc/rc.d/rc.foo> 

This is the example run-command script of an B<OpenPKG> package C<foo>.
It is installed by package C<foo> and used read-only.

 #!/cw/etc/rc
 %config
     foo_enable=yes
     foo_flags=""
 %common
     foo_pidfile=/cw/var/foo/foo.pid
 %start -u root -p 100
     if opServiceEnabled foo; then
         /cw/sbin/foo -p $foo_pidfile -S $foo_flags
     fi
 %stop -u root -p 100
     if opServiceEnabled foo; then
         /cw/sbin/foo -p $foo_pidfile -K
     fi
 %restart -u root -p 100
     if opServiceEnabled foo; then
         %stop
         sleep 1
         %start 
     fi
 %env
     if opServiceEnabled foo; then
         FOO=/cw/sbin/foo
         export FOO
     fi

=back

With this setup, the following use cases are possible:

 $ /cw/etc/rc --query "foo enabled: %{foo_enable}"
 foo enabled: yes
 $ _

 $ /cw/etc/rc --config
 Configuration Variable   Effective Value              Default Value
 ------------------------ ------------------------- -- -------------------------
 foo_enable               "yes"                     == "yes"                    
 foo_flags                "--sample"                != ""                    
 $ _ 

 $ /cw/etc/rc -v foo start
 start: foo
 $ _ 

 $ /cw/etc/rc --print foo env
 # /cw/etc/rc.d/rc.foo 3
     foo_enable=yes
     foo_flags=""
 # /cw/etc/rc.conf 1
 foo_enable=yes
 foo_flags="--sample"
 # internal 0
     . /cw/etc/rc.func
 # /cw/etc/rc.d/rc.foo 6
     foo_pidfile=/cw/var/foo/foo.pid
 # /cw/etc/rc.d/rc.foo 22
     if opServiceEnabled foo; then
         FOO="The Foo"
         export FOO
     fi
 $ _

 $ eval `/cw/etc/rc --eval foo env`
 $ print $FOO
 The Foo
 $ _

=head1 USE CASE: Dynamic User Environment (DUE)

 ....

#   rc configuration for Dynamic User Environment (DUE)
Dirs          .:..//
Name          .duerc
RequireUmask  022      
RequireOwner  $USER           
RequireGroup  %{GROUP}

 ....

=cut