OpenPKG Specs / file revision

 .\" Automatically generated by Pod::Man 2.25 (Pod::Simple 3.22)

 .\"

 .\" Standard preamble:

 .\" ========================================================================

 .de Sp \" Vertical space (when we can't use .PP)

 .if t .sp .5v

 .if n .sp

 ..

 .de Vb \" Begin verbatim text

 .ft CW

 .nf

 .ne \\$1

 ..

 .de Ve \" End verbatim text

 .ft R

 .fi

 ..

 .\" Set up some character translations and predefined strings.  \*(-- will

 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left

 .\" double quote, and \*(R" will give a right double quote.  \*(C+ will

 .\" give a nicer C++.  Capital omega is used to do unbreakable dashes and

 .\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,

 .\" nothing in troff, for use with C<>.

 .tr \(*W-

 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'

 .ie n \{\

 .    ds -- \(*W-

 .    ds PI pi

 .    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch

 .    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch

 .    ds L" ""

 .    ds R" ""

 .    ds C` 

 .    ds C' 

 'br\}

 .el\{\

 .    ds -- \|\(em\|

 .    ds PI \(*p

 .    ds L" ``

 .    ds R" ''

 'br\}

 .\"

 .\" Escape single quotes in literal strings from groff's Unicode transform.

 .ie \n(.g .ds Aq \(aq

 .el       .ds Aq '

 .\"

 .\" If the F register is turned on, we'll generate index entries on stderr for

 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index

 .\" entries marked with X<> in POD.  Of course, you'll have to process the

 .\" output yourself in some meaningful fashion.

 .ie \nF \{\

 .    de IX

 .    tm Index:\\$1\t\\n%\t"\\$2"

 ..

 .    nr % 0

 .    rr F

 .\}

 .el \{\

 .    de IX

 ..

 .\}

 .\"

 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).

 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.

 .    \" fudge factors for nroff and troff

 .if n \{\

 .    ds #H 0

 .    ds #V .8m

 .    ds #F .3m

 .    ds #[ \f1

 .    ds #] \fP

 .\}

 .if t \{\

 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)

 .    ds #V .6m

 .    ds #F 0

 .    ds #[ \&

 .    ds #] \&

 .\}

 .    \" simple accents for nroff and troff

 .if n \{\

 .    ds ' \&

 .    ds ` \&

 .    ds ^ \&

 .    ds , \&

 .    ds ~ ~

 .    ds /

 .\}

 .if t \{\

 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"

 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'

 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'

 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'

 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'

 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'

 .\}

 .    \" troff and (daisy-wheel) nroff accents

 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'

 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'

 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]

 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'

 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'

 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]

 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]

 .ds ae a\h'-(\w'a'u*4/10)'e

 .ds Ae A\h'-(\w'A'u*4/10)'E

 .    \" corrections for vroff

 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'

 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'

 .    \" for low resolution devices (crt and lpr)

 .if \n(.H>23 .if \n(.V>19 \

 \{\

 .    ds : e

 .    ds 8 ss

 .    ds o a

 .    ds d- d\h'-1'\(ga

 .    ds D- D\h'-1'\(hy

 .    ds th \o'bp'

 .    ds Th \o'LP'

 .    ds ae ae

 .    ds Ae AE

 .\}

 .rm #[ #] #H #V #F C

 .\" ========================================================================

 .\"

 .IX Title "RC 8"

 .TH RC 8 "OpenPKG" "RC(8)" "OpenPKG"

 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes

 .\" way too many mistakes in technical documents.

 .if n .ad l

 .nh

 .SH "NAME"

 @l_prefix@/bin/openpkg rc \- OpenPKG Run\-Command Processor

 .SH "SYNOPSIS"

 .IX Header "SYNOPSIS"

 \&\fB\f(CB@l_prefix\fB@/bin/openpkg rc\fR [\fB\-s\fR|\fB\-\-silent\fR] [\fB\-v\fR|\fB\-\-verbose\fR] [\fB\-d\fR|\fB\-\-debug\fR] [\fB\-k\fR|\fB\-\-keep\fR] [\fB\-D\fR|\fB\-\-define\fR \fIname\fR=\fIvalue\fR] \fIpackage\fR \fIcommand\fR [\fIcommand\fR ...]

 .PP

 \&\fB\f(CB@l_prefix\fB@/bin/openpkg rc\fR \fB\-p\fR|\fB\-\-print\fR \fIpackage\fR \fIcommand\fR [\fIcommand\fR ...]

 .PP

 eval `\fB\f(CB@l_prefix\fB@/bin/openpkg rc\fR \fB\-e\fR|\fB\-\-eval\fR \fIpackage\fR \fIcommand\fR [\fIcommand\fR ...]`

 .PP

 \&\fB\f(CB@l_prefix\fB@/bin/openpkg rc\fR \fB\-q\fR|\fB\-\-query\fR \fIvariable\fR [\fIvariable\fR ...]

 .PP

 \&\fB\f(CB@l_prefix\fB@/bin/openpkg rc\fR \fB\-c\fR|\fB\-\-config\fR

 .PP

 \&\fB\f(CB@l_prefix\fB@/bin/openpkg rc\fR \fB\-h\fR|\fB\-\-help\fR

 .SH "DESCRIPTION"

 .IX Header "DESCRIPTION"

 The \fB\f(CB@l_prefix\fB@/bin/openpkg rc\fR program is the run-command (rc) processor

 of the \fBOpenPKG\fR instance \f(CW\*(C`@l_prefix@\*(C'\fR. It allows querying the rc

 configuration variables and the execution of rc command scripts of one

 or more installed \fBOpenPKG\fR packages. The implemented run-command

 facility is partly modeled after the classical \s-1UNIX\s0(tm) System V

 run-command facility plus ideas taken from the FreeBSD and NetBSD

 run-command facilities. It mainly merges the classical startup/shutdown

 procedures with periodical procedures into a single approach.

 .SH "USAGE"

 .IX Header "USAGE"

 .ie n .IP "\fB\fB@l_prefix\fB@/bin/openpkg rc\fR [\fB\-s\fR|\fB\-\-silent\fR] [\fB\-v\fR|\fB\-\-verbose\fR] [\fB\-d\fR|\fB\-\-debug\fR] [\fB\-k\fR|\fB\-\-keep\fR] [\fB\-D\fR|\fB\-\-define\fR \fIname\fR=\fIvalue\fR] \fIpackage\fR \fIcommand\fR [\fIcommand\fR ...]" 4

 .el .IP "\fB\f(CB@l_prefix\fB@/bin/openpkg rc\fR [\fB\-s\fR|\fB\-\-silent\fR] [\fB\-v\fR|\fB\-\-verbose\fR] [\fB\-d\fR|\fB\-\-debug\fR] [\fB\-k\fR|\fB\-\-keep\fR] [\fB\-D\fR|\fB\-\-define\fR \fIname\fR=\fIvalue\fR] \fIpackage\fR \fIcommand\fR [\fIcommand\fR ...]" 4

 .IX Item "@l_prefix@/bin/openpkg rc [-s|--silent] [-v|--verbose] [-d|--debug] [-k|--keep] [-D|--define name=value] package command [command ...]"

 \&\fBRun-Command Execution.\fR This executes one or more specified

 \&\fIcommand\fRs in a particular \fIpackage\fR or in all installed packages if

 \&\fIpackage\fR is "\f(CW\*(C`all\*(C'\fR". Option \fB\-\-silent\fR can be used to explicitly

 disable progress messages on \f(CW\*(C`stderr\*(C'\fR. Option \fB\-\-verbose\fR can be used

 to explicitly enable progress messages on \f(CW\*(C`stderr\*(C'\fR. By default, \fBrc\fR

 automatically determines whether progress messages should be displayed

 or not depending on whether \f(CW\*(C`stderr\*(C'\fR is connected to a terminal device.

 Option \fB\-\-keep\fR can be used for debugging purposes to keep the

 temporary files were generated during internal processing. Option

 \&\fB\-\-define\fR can be used to on-the-fly re-define a configuration variable

 \&\fIname\fR with \fIvalue\fR.

 .ie n .IP "\fB\fB@l_prefix\fB@/bin/openpkg rc\fR \fB\-p\fR|\fB\-\-print\fR \fIpackage\fR \fIcommand\fR [\fIcommand\fR ...]" 4

 .el .IP "\fB\f(CB@l_prefix\fB@/bin/openpkg rc\fR \fB\-p\fR|\fB\-\-print\fR \fIpackage\fR \fIcommand\fR [\fIcommand\fR ...]" 4

 .IX Item "@l_prefix@/bin/openpkg rc -p|--print package command [command ...]"

 \&\fBRun-Command Printing.\fR This is like the run-command execution (see

 above), but instead of immediately executing all involved individual

 run-command scripts, they are concatenated (but with all configuration

 parts reduced to a single configuration part) and printed to \f(CW\*(C`stdout\*(C'\fR.

 Use this for debugging or post-processing purposes.

 .ie n .IP "eval `\fB\fB@l_prefix\fB@/bin/openpkg rc\fR \fB\-e\fR|\fB\-\-eval\fR \fIpackage\fR \fIcommand\fR [\fIcommand\fR ...]`" 4

 .el .IP "eval `\fB\f(CB@l_prefix\fB@/bin/openpkg rc\fR \fB\-e\fR|\fB\-\-eval\fR \fIpackage\fR \fIcommand\fR [\fIcommand\fR ...]`" 4

 .IX Item "eval `@l_prefix@/bin/openpkg rc -e|--eval package command [command ...]`"

 \&\fBRun-Command Evaluation.\fR This is like the run-command execution

 (see above), but the resulting exported shell environment variables

 are output to a temporary file as a (Bourne-Shell or C\-Shell syntax)

 shell script, suitable for evaluation within the shell environment

 of the caller. A one-line script is printed to \f(CW\*(C`stdout\*(C'\fR which then

 \&\*(L"sources\*(R" (and immediately removes) this temporary file. This is

 slightly different from printing the temporary script directly to

 \&\f(CW\*(C`stdout\*(C'\fR, because not all shell implementations like to "\fBeval\fR\*(L"

 large multi-line scripts. Hence, use this for executing the \*(R"\f(CW\*(C`env\*(C'\fR"

 run-commands within the current shell.

 .ie n .IP "\fB\fB@l_prefix\fB@/bin/openpkg rc\fR \fB\-q\fR|\fB\-\-query\fR \fIvariable\fR [\fIvariable\fR ...]" 4

 .el .IP "\fB\f(CB@l_prefix\fB@/bin/openpkg rc\fR \fB\-q\fR|\fB\-\-query\fR \fIvariable\fR [\fIvariable\fR ...]" 4

 .IX Item "@l_prefix@/bin/openpkg rc -q|--query variable [variable ...]"

 \&\fBConfiguration Variable Querying.\fR This queries the effective values

 (see \fBRUN-COMMAND \s-1CONFIGURATION\s0\fR section below) of one or more

 run-command configuration \fIvariable\fRs. Use this within a shell script

 to selectively query a particular variable.

 .ie n .IP "\fB\fB@l_prefix\fB@/bin/openpkg rc\fR \fB\-c\fR|\fB\-\-config\fR" 4

 .el .IP "\fB\f(CB@l_prefix\fB@/bin/openpkg rc\fR \fB\-c\fR|\fB\-\-config\fR" 4

 .IX Item "@l_prefix@/bin/openpkg rc -c|--config"

 \&\fBConfiguration Variable Summary.\fR This displays on \f(CW\*(C`stdout\*(C'\fR a

 three-column table showing the name, default and effective values of

 all run-command configuration variables. If \f(CW\*(C`stdout\*(C'\fR is connected to

 terminal device, variables where the default and effective values differ

 are shown in bold mode.

 .ie n .IP "\fB\fB@l_prefix\fB@/bin/openpkg rc\fR \fB\-h\fR|\fB\-\-help\fR" 4

 .el .IP "\fB\f(CB@l_prefix\fB@/bin/openpkg rc\fR \fB\-h\fR|\fB\-\-help\fR" 4

 .IX Item "@l_prefix@/bin/openpkg rc -h|--help"

 \&\fBRequesting Help.\fR This just displays a short summary of

 the usage for this program.

 .SH "FILES"

 .IX Header "FILES"

 .ie n .SS "RUN-COMMAND \s-1FILES\s0 (\*(C`@l_prefix@/bin/openpkg rc.d/rc.*\*(C')"

 .el .SS "RUN-COMMAND \s-1FILES\s0 (\f(CW\*(C`@l_prefix@/bin/openpkg rc.d/rc.*\*(C'\fP)"

 .IX Subsection "RUN-COMMAND FILES (@l_prefix@/bin/openpkg rc.d/rc.*)"

 The foundation of the \fBOpenPKG\fR run-command facility are the individual

 run-command files \f(CW\*(C`rc.*\*(C'\fR of the installed packages. They are all

 located in the directory \f(CW\*(C`@l_prefix@/bin/openpkg rc.d/\*(C'\fR and are named

 "\f(CW\*(C`rc.\*(C'\fR\fIpackage\fR\*(L". They consist of one or more sections, each starting

 with a section header \*(R"\f(CW\*(C`%\*(C'\fR\fIname\fR [\fIoptions\fR]" and following a \s-1GNU\s0

 Bash compatible shell script. There are three classes of sections:

 .IP "\fBSpecial Sections\fR" 4

 .IX Item "Special Sections"

 There are 2 sections which have a special meaning to the \fBrc\fR program

 and cannot be used for different purposes.

 .RS 4

 .ie n .IP "%config" 4

 .el .IP "\f(CW%config\fR" 4

 .IX Item "%config"

 This section has to consist of run-command configuration

 variable default settings in Bourne-Shell syntax only, i.e.,

 it has to contain one or more lines, each of exactly the form

 "\fIpackage\fR\f(CW\*(C`_\*(C'\fR\fIvariable\fR\f(CW\*(C`=\*(C'\fR\fIvalue\fR\*(L". Notice that in section

 \&\*(R"\f(CW%config\fR\*(L" of run-command file \*(R"\f(CW\*(C`rc.foo\*(C'\fR\*(L" the variables all have

 to be prefixed (by convention) with \*(R"\f(CW\*(C`foo_\*(C'\fR". It is allowed that the

 \&\fIvalue\fRs reference other variables defined before in the same section

 or from the "\f(CW%config\fR\*(L" section of the bootstrap package \*(R"\f(CW\*(C`openpkg\*(C'\fR".

 Additionally, by convention all lines have to be indented by 4 spaces.

 .Sp

 \&\s-1NOTICE:\s0 All sections of all run-command scripts see all \f(CW%config\fR

 sections of all packages.

 .ie n .IP "%common" 4

 .el .IP "\f(CW%common\fR" 4

 .IX Item "%common"

 This section can consist of an arbitrary shell script

 which is automatically prepended to the shell scripts

 of all other sections on execution. It is usually used

 to define common and local variables and functions.

 .RE

 .RS 4

 .RE

 .IP "\fBConventional Sections\fR" 4

 .IX Item "Conventional Sections"

 There are 9 sections which have no special meaning to the \fBrc\fR program,

 but are used in \fBOpenPKG\fR by convention for standard purposes. Hence,

 do not use them for arbitrary things instead.

 .Sp

 Throughout these sections it is possible to specify the user to be

 switched to before the code is executed.

 .Sp

 A priority can be given for each section to control execution sequence

 if "\f(CW\*(C`all\*(C'\fR" packages are given. Higher priority leads to earlier

 starting and later stopping. The priority is a number where low numbers

 mean high priority (numerically sorted for starting). If omitted, the

 priority defaults to 500.

 .Sp

 Output generated on \fIstdout\fR and \fIstderr\fR is captured and normally

 suppressed. In case the sections script exits with a non-zero return

 value, the intercepted messages are consolidated, reformatted with a

 surrounding ASCII-art border and printed to \fIstderr\fR. If the section

 is tagged with option \fB\-o\fR, \fIstdout\fR messages are passed through

 verbatim, even if the section script exists with a zero return value.

 .RS 4

 .ie n .IP "%start [\fB\-u\fR \fIuser\fR] [\fB\-p\fR \fIpriority\fR]" 4

 .el .IP "\f(CW%start\fR [\fB\-u\fR \fIuser\fR] [\fB\-p\fR \fIpriority\fR]" 4

 .IX Item "%start [-u user] [-p priority]"

 This section should start daemons or initialize components.

 It is especially executed by \fBOpenPKG\fR during system startup.

 .ie n .IP "%stop [\fB\-u\fR \fIuser\fR] [\fB\-p\fR \fIpriority\fR]" 4

 .el .IP "\f(CW%stop\fR [\fB\-u\fR \fIuser\fR] [\fB\-p\fR \fIpriority\fR]" 4

 .IX Item "%stop [-u user] [-p priority]"

 This section should stop daemons or cleaning up components. It is

 especially executed by \fBOpenPKG\fR during system shutdown and package

 deinstallation.

 .ie n .IP "%restart [\fB\-u\fR \fIuser\fR] [\fB\-p\fR \fIpriority\fR]" 4

 .el .IP "\f(CW%restart\fR [\fB\-u\fR \fIuser\fR] [\fB\-p\fR \fIpriority\fR]" 4

 .IX Item "%restart [-u user] [-p priority]"

 This section should restart daemons.

 It is especially executed by \fBOpenPKG\fR during package upgrades.

 .ie n .IP "\*(C`%status \-o\*(C' [\fB\-u\fR \fIuser\fR] [\fB\-p\fR \fIpriority\fR]" 4

 .el .IP "\f(CW\*(C`%status \-o\*(C'\fR [\fB\-u\fR \fIuser\fR] [\fB\-p\fR \fIpriority\fR]" 4

 .IX Item "%status -o [-u user] [-p priority]"

 This section has to provide status information for a package

 by printing to \f(CW\*(C`stdout\*(C'\fR (hence the \fB\-o\fR option is always required),

 in Bourne-Shell syntax, the definition of three variables:

 .RS 4

 .ie n .IP "\fIpackage\fR\*(C`_enable\*(C'" 4

 .el .IP "\fIpackage\fR\f(CW\*(C`_enable\*(C'\fR" 4

 .IX Item "package_enable"

 Whether package is enabled, i.e., whether it accepts run-commands. This

 variable just has to be printed, because is already set in current

 script environment.

 .ie n .IP "\fIpackage\fR\*(C`_usable\*(C'" 4

 .el .IP "\fIpackage\fR\f(CW\*(C`_usable\*(C'\fR" 4

 .IX Item "package_usable"

 Whether package is usable, i.e., whether it is already correctly

 configured, etc. This variable has to be individually determined.

 .ie n .IP "\fIpackage\fR\*(C`_active\*(C'" 4

 .el .IP "\fIpackage\fR\f(CW\*(C`_active\*(C'\fR" 4

 .IX Item "package_active"

 Whether package is active, i.e., whether it is already running.

 This variable has to be individually determined.

 .RE

 .RS 4

 .RE

 .ie n .IP "%monthly [\fB\-u\fR \fIuser\fR] [\fB\-p\fR \fIpriority\fR]" 4

 .el .IP "\f(CW%monthly\fR [\fB\-u\fR \fIuser\fR] [\fB\-p\fR \fIpriority\fR]" 4

 .IX Item "%monthly [-u user] [-p priority]"

 .PD 0

 .ie n .IP "%weekly [\fB\-u\fR \fIuser\fR] [\fB\-p\fR \fIpriority\fR]" 4

 .el .IP "\f(CW%weekly\fR [\fB\-u\fR \fIuser\fR] [\fB\-p\fR \fIpriority\fR]" 4

 .IX Item "%weekly [-u user] [-p priority]"

 .ie n .IP "%hourly [\fB\-u\fR \fIuser\fR] [\fB\-p\fR \fIpriority\fR]" 4

 .el .IP "\f(CW%hourly\fR [\fB\-u\fR \fIuser\fR] [\fB\-p\fR \fIpriority\fR]" 4

 .IX Item "%hourly [-u user] [-p priority]"

 .ie n .IP "%quarterly [\fB\-u\fR \fIuser\fR] [\fB\-p\fR \fIpriority\fR]" 4

 .el .IP "\f(CW%quarterly\fR [\fB\-u\fR \fIuser\fR] [\fB\-p\fR \fIpriority\fR]" 4

 .IX Item "%quarterly [-u user] [-p priority]"

 .PD

 These sections should perform periodical tasks for a package and

 are executed on a monthly, weekly, hourly or quarterly basis.

 .ie n .IP "%env" 4

 .el .IP "\f(CW%env\fR" 4

 .IX Item "%env"

 This section is intended to export one or more environment variables

 which are imported into the shell environment of the caller through the

 \&\fB\-\-eval\fR command line option.

 .RE

 .RS 4

 .RE

 .IP "\fBCustom Sections\fR" 4

 .IX Item "Custom Sections"

 All other sections are custom ones and can be fully individual to each

 package. Some often seen sections are \f(CW%reload\fR (just reload the

 configuration without full stop and start procedure), \f(CW%info\fR (output

 arbitrary information about package), etc.

 .ie n .SS "RUN-COMMAND \s-1CONFIGURATION\s0 (\*(C`@l_prefix@/bin/openpkg rc.conf\*(C')"

 .el .SS "RUN-COMMAND \s-1CONFIGURATION\s0 (\f(CW\*(C`@l_prefix@/bin/openpkg rc.conf\*(C'\fP)"

 .IX Subsection "RUN-COMMAND CONFIGURATION (@l_prefix@/bin/openpkg rc.conf)"

 The run-command configuration variables defined in the "\f(CW%config\fR"

 sections of all installed packages can be overridden by the

 administrator in the global file \f(CW\*(C`@l_prefix@/bin/openpkg rc.conf\*(C'\fR. This file is

 usually empty, but can be filled with Bourne-Shell compatible variable

 assignment statements like "\fIpackage\fR\f(CW\*(C`_\*(C'\fR\fIvariable\fR=\fIvalue\fR".

 .ie n .SS "RUN-COMMAND \s-1FUNCTIONS\s0 (\*(C`@l_prefix@/bin/openpkg rc.func\*(C')"

 .el .SS "RUN-COMMAND \s-1FUNCTIONS\s0 (\f(CW\*(C`@l_prefix@/bin/openpkg rc.func\*(C'\fP)"

 .IX Subsection "RUN-COMMAND FUNCTIONS (@l_prefix@/bin/openpkg rc.func)"

 The file \f(CW\*(C`@l_prefix@/bin/openpkg rc.func\*(C'\fR is prepended to the scripts of all

 executed run-command sections and provides reusable functions.

 Currently the following functions are defined:

 .IP "\fBrcMsg\fR [\fB\-e\fR] [\fB\-w\fR] \fImessage\fR" 4

 .IX Item "rcMsg [-e] [-w] message"

 Print a message to the output device of the run-command caller. The

 message is printed to the captured \fIstderr\fR (but are visible to

 the caller of the run-command script only if the script fails). All

 messages are prefixed with "\f(CW\*(C`rc:\*(C'\fR". If option \fB\-e\fR is given, the

 prefix is "\f(CW\*(C`rc:ERROR:\*(C'\fR". If option \fB\-w\fR is given, the prefix is

 "\f(CW\*(C`rc:WARNING:\*(C'\fR".

 .IP "\fBrcPath\fR [\fB\-a\fR] [\fB\-r\fR] [\fB\-p\fR] [\fB\-e\fR] \fIvariable\fR \fIdir\fR [\fIdir\fR ...]" 4

 .IX Item "rcPath [-a] [-r] [-p] [-e] variable dir [dir ...]"

 Add (option \fB\-a\fR) or remove (option \fB\-r\fR) one or more \fIdir\fRectories

 to/from the colon-separated value of a \fIvar\fRable. By default, on

 addition, the directory is appended to the end, if option \fB\-p\fR is used

 the directory is prepended to the start. If option \fB\-e\fR is used, the

 directories are added only if they exist on the underlying filesystem.

 Use this function for conveniently manipulating \f(CW\*(C`PATH\*(C'\fR, \f(CW\*(C`MANPATH\*(C'\fR,

 \&\f(CW\*(C`INFOPATH\*(C'\fR, \f(CW\*(C`LD_LIBRARY_PATH\*(C'\fR and similar variables.

 .IP "\fBrcTmp\fR [\fB\-i\fR] [\fB\-f\fR] [\fB\-n\fR \fIname\fR] [\fB\-k\fR]" 4

 .IX Item "rcTmp [-i] [-f] [-n name] [-k]"

 Convenience interface to secure temporary file handling. Option \fB\-i\fR

 first has to be used to initialize a secure temporary directory (option

 \&\fB\-k\fR later will kill this again). Under option \fB\-f\fR you then can get

 reasonable temporary filenames under the created temporary directory. By

 default, the temporary filename is just "\f(CW\*(C`tmp\*(C'\fR", but can be specified

 with option \fB\-n\fR to be \fIname\fR.

 .IP "\fBrcService\fR \fIpackage\fR \fIstatus\fR \fIvalue\fR" 4

 .IX Item "rcService package status value"

 Convenience interface to checking the \f(CW%status\fR variables

 \&\fIpackage\fR\f(CW\*(C`_\*(C'\fR\fIstatus\fR which have to be provided by the \f(CW%config\fR (if

 \&\fIstatus\fR is "\f(CW\*(C`enable\*(C'\fR" this is enough) and \f(CW%status\fR (if \fIstatus\fR is

 "\f(CW\*(C`enable\*(C'\fR\*(L", \*(R"\f(CW\*(C`usable\*(C'\fR\*(L" and \*(R"\f(CW\*(C`active\*(C'\fR"). The \fBrcService\fR especially

 caches the resolving of the variable values. Returns 0 if the resolved

 value is \fIvalue\fR, else returns 1.

 .IP "\fBrcVarIsYes\fR \fIname\fR" 4

 .IX Item "rcVarIsYes name"

 Checks whether variable \fIname\fR has a value of "\f(CW\*(C`yes\*(C'\fR\*(L", \*(R"\f(CW\*(C`true\*(C'\fR\*(L",

 \&\*(R"\f(CW\*(C`on\*(C'\fR\*(L", or \*(R"\f(CW1\fR" (with arbitrary lower or upper case letters). Returns

 0 if value is one of these positive ones, else returns 1.

 .SH "EXAMPLES"

 .IX Header "EXAMPLES"

 First, an example run-command script \f(CW\*(C`@l_prefix@/bin/openpkg rc.d/rc.foo\*(C'\fR for a

 fictional daemon package "\f(CW\*(C`foo\*(C'\fR":

 .PP

 .Vb 8

 \& %config

 \&    foo_enable="${openpkg_rc_def}"

 \&    foo_listen="127.0.0.1"

 \&    foo_log_prolog="true"

 \&    foo_log_epilog="true"

 \&    foo_log_numfiles="10"

 \&    foo_log_minsize="1M"

 \&    foo_log_complevel="9"

 \&

 \& %common

 \&    foo_homedir="@l_prefix@/share/foo"

 \&    foo_cfgfile="@l_prefix@/etc/foo/foo.cfg"

 \&    foo_pidfile="@l_prefix@/var/foo/foo.pid"

 \&    foo_logfile="@l_prefix@/var/foo/foo.log"

 \&    foo_signal () {

 \&        if [ \-f ${foo_pidfile} ]; then

 \&            kill \-$1 \`cat ${foo_pidfile}\`

 \&            return $?

 \&        else

 \&            return 1

 \&        fi

 \&    }

 \&

 \& %status

 \&     foo_usable="no"

 \&     if [ ".\`grep \*(Aq<<PASSWORD>>\*(Aq ${foo_cfgfile}\`" = . ]; then

 \&         foo_usable="yes"

 \&     fi

 \&     foo_active="no"

 \&     if [ \-f ${foo_pidfile} ]; then

 \&         foo_signal 0

 \&         if [ $? \-eq 0 ]; then

 \&             foo_active="yes"

 \&         fi

 \&     fi

 \&     echo "foo_enable=${foo_enable}"

 \&     echo "foo_usable=${foo_usable}"

 \&     echo "foo_active=${foo_active}"

 \&

 \& %start

 \&     rcService foo enable yes || exit 0

 \&     rcService foo active yes && exit 0

 \&     @l_prefix@/sbin/foo \-\-listen ${foo_listen}

 \&

 \& %stop

 \&     rcService foo enable yes || exit 0

 \&     rcService foo active yes || exit 0

 \&     foo_signal TERM

 \&

 \& %restart

 \&     rcService foo enable yes || exit 0

 \&     rcService foo active yes || exit 0

 \&     rc foo stop start

 \&

 \& %daily

 \&     rcService foo enable yes || exit 0

 \&     shtool rotate \-f \e

 \&         \-n ${foo_log_numfiles} \-s ${foo_log_minsize} \-d \e

 \&         \-z ${foo_log_complevel} \-o @l_rusr@ \-g @l_rgrp@ \-m 644 \e

 \&         \-P "${foo_log_prolog}" \-E "${foo_log_epilog}" \e

 \&         ${foo_logfile}

 \&

 \& %env

 \&     if rcService foo enable yes; then

 \&         FOO_HOME="$foo_homedir"

 \&         export FOO_HOME

 \&     fi

 .Ve

 .PP

 Now, show all run-command configuration variables, their

 default values and their effective values of package "\f(CW\*(C`foo\*(C'\fR":

 .PP

 .Vb 1

 \& $ @l_prefix@/bin/openpkg rc \-\-config | grep "^foo_"

 .Ve

 .PP

 Override the default value of a run-command configuration

 variable \f(CW\*(C`foo_listen\*(C'\fR:

 .PP

 .Vb 1

 \& $ echo \*(Aqfoo_listen="192.168.0.1"\*(Aq >>@l_prefix@/bin/openpkg rc.conf

 .Ve

 .PP

 Stop and start from scratch the package "\f(CW\*(C`foo\*(C'\fR":

 .PP

 .Vb 1

 \& $ @l_prefix@/bin/openpkg rc foo stop start

 .Ve

 .PP

 Query the effective value of run-command configuration

 variable \f(CW\*(C`foo_enable\*(C'\fR in a script:

 .PP

 .Vb 1

 \& if [ ".\`@l_prefix@/bin/openpkg rc \-q foo_enable\`" = .yes ]; then ...

 .Ve

 .PP

 Import all environment settings from all (including "\f(CW\*(C`foo\*(C'\fR") installed

 packages into the current Bourne-Shell environment:

 .PP

 .Vb 2

 \& $ eval \`@l_prefix@/bin/openpkg rc \-\-eval all env\`

 \& $ echo $FOO_HOME

 .Ve

 .SH "SEE ALSO"

 .IX Header "SEE ALSO"

 \&\fBOpenPKG\fR http://www.openpkg.org/

 .SH "HISTORY"

 .IX Header "HISTORY"

 The \fBOpenPKG\fR run-command facility consisting of the scripts \f(CW\*(C`rc\*(C'\fR

 and \f(CW\*(C`rc.func\*(C'\fR were originally invented in November 2000 by Ralf S.

 Engelschall for \fBOpenPKG\fR. They were completely worked off from scratch

 in July 2003 for \fBOpenPKG 1.3\fR.

 .SH "AUTHOR"

 .IX Header "AUTHOR"

 .Vb 3

 \& Ralf S. Engelschall

 \& rse@engelschall.com

 \& www.engelschall.com

 .Ve