Index: ossp-pkg/rc/rc-sample.pod
RCS File: /v/ossp/cvs/ossp-pkg/rc/rc-sample.pod,v
co -q -kk -p'1.1' '/v/ossp/cvs/ossp-pkg/rc/rc-sample.pod,v' | diff -u /dev/null - -L'ossp-pkg/rc/rc-sample.pod' 2>/dev/null
--- ossp-pkg/rc/rc-sample.pod
+++ -	2024-05-06 15:19:40.446047319 +0200
@@ -0,0 +1,169 @@
+
+=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