diff options
Diffstat (limited to 'doc/pies.texi')
-rw-r--r-- | doc/pies.texi | 210 |
1 files changed, 200 insertions, 10 deletions
diff --git a/doc/pies.texi b/doc/pies.texi index b77a40c..ccb9f0e 100644 --- a/doc/pies.texi +++ b/doc/pies.texi @@ -122,6 +122,7 @@ Component Statement * Prerequisites:: * Component Privileges:: * Resources:: +* Environment:: * Actions Before Startup:: * Exit Actions:: * Output Redirectors:: @@ -712,7 +713,7 @@ compatibility with the @sc{c} preprocessor. @end table @node Component Statement -@section Component Statement +@section The @code{component} Statement @kwindex component @deffn {Config} component @@ -937,6 +938,7 @@ substatements. * Prerequisites:: * Component Privileges:: * Resources:: +* Environment:: * Actions Before Startup:: * Exit Actions:: * Output Redirectors:: @@ -1038,7 +1040,122 @@ Set the umask. The @var{number} must be an octal value not greater than @samp{777}. The default umask is inherited at startup. @end deffn -@deffn {Config: component} env @var{args} +@deffn {Config: component} max-instances @var{n} +Sets the maximum number of simultaneously running instances of this +component. +@end deffn + +@node Environment +@subsection Environment +Normally all components inherit the environment of the master +@command{pies} process. You can modify this environment using +the @code{env} statement. It has two variants: @dfn{compound} and @dfn{legacy}. +The legacy one-line statement was used in @command{pies} versions +up to 1.3 and is still retained for backward compatibility. It is +described in @ref{env legacy syntax}. This subsection describes the +modern compount syntax. + +@deffn {Config: component} env @{ ... @} +The compound @code{env} statement has the following syntax: + +@example +@group +env @{ + clear @var{bool}; + keep @var{pattern}; + set "@var{name}=@var{value}"; + unset @var{pattern}; +@} +@end group +@end example +@end deffn + +Statements inside the @code{env} block define operations that +modify the environment. The @code{clear} and @code{keep} statements +are executed first. Then, the @code{set} and @code{unset} statements +are applied in the order of their appearance in the configuration. + +@deffn {env} clear @var{bool} +If @var{bool} is @samp{yes}, all environment variables will be cleared +(unset). The resulting environment will be empty, unless one or more +@code{keep} statements are also given (see below). The @code{clear} +statement is always executed first. +@end deffn + +@deffn {env} keep @var{pattern} +Declares variables matching @var{pattern} (a globbing pattern) as +exempt from clearing. This statement implies @code{clear}. + +For example, the following configuration fragment removes from the +environment all variables except @samp{HOME}, @samp{USER}, +@samp{PATH}, and variables beginning with @samp{LC_}: + +@example +@group +env @{ + clear yes; + keep HOME; + keep USER; + keep PATH; + keep "LC_*"; +@} +@end group +@end example +@end deffn + +@deffn {env} keep "@var{name}=@var{value}" +Retains the variable @var{name}, if it has the given value. Note, that +the argument must be quoted. +@end deffn + +@deffn {env} set "@var{name}=@var{value}" +Assigns @var{value} to environment variable @var{name}. The value is +subject to @dfn{variable expansion} using the same syntax as in shell. +The @code{set} and @code{unset} (see below) statements are executed in +order of their appearance. For example + +@example +@group +env @{ + set "MYLIB=$HOME/lib"; + set "LD_LIBRARY_PATH=$LD_LIBRARY_PATH$@{LD_LIBRARY_PATH:+:@}$MYLIB"; +@} +@end group +@end example +@end deffn + +@deffn {env} unset @var{pattern} +Unset environment variables matching @var{pattern}. The following +will unset the @env{LOGIN} variable: + +@example +unset LOGIN; +@end example + +@noindent +The following will unset all variables starting with @samp{LD_}: + +@example +unset "LD_*"; +@end example + +@noindent +Notice, that patterns containing wildcard characters must be quoted. +@end deffn + +@menu +* env legacy syntax:: +@end menu + +@node env legacy syntax +@subsubsection @code{env}: legacy syntax. +Up to version 1.3 @command{pies} implemented the one-line variant of +the @code{env} statement. The use of this legacy syntax is +discouraged. It is supported for backward compatibility only and will +be removed in future versions. This subsection describes the legacy +syntax. + +@deffn {legacy syntax} env @var{args} Set program environment. Arguments are a whitespace-delimited list of specifiers. The @@ -1049,17 +1166,63 @@ following specifiers are understood: Clear the environment. This is understood only when used as a first word in @var{args}. +The modern syntax equivalent is: + +@example +@group +env @{ + clear yes; +@} +@end group +@end example + @item -@var{name} -Unset the environment variable @var{name}. +Unset the environment variable @var{name}. The modern syntax +equivalent is + +@example +@group +env @{ + unset @var{name}; +@} +@end group +@end example @item -@var{name}=@var{val} Unset the environment variable @var{name} only if its value is @var{val}. +The modern syntax equivalent is: + +@example +@group +env @{ + unset "@var{name}=@var{val}"; +@} +@end group +@end example @item @var{name} -Retain the environment variable @var{name}. +Retain the environment variable @var{name}. The modern syntax +equivalent is + +@example +@group +env @{ + keep @var{name}; +@} +@end group +@end example @item @var{name}=@var{value} -Define environment variable @var{name} to have given @var{value}. +Define environment variable @var{name} to have given @var{value}. The +modern syntax equivalent is: + +@example +@group +env @{ + keep "@var{name}=@var{value}"; +@} +@end group +@end example @item @var{name}+=@var{value} Retain variable @var{name} and append @var{value} to its existing @@ -1077,18 +1240,42 @@ In this example, if @env{PATH} exists, @samp{:/sbin} will be appended to it. Otherwise, it will be created and @samp{/sbin} will be assigned to it. +In modern syntax, use shell variable references, e.g.: + +@example +@group +env @{ + set "PATH=$@{PATH@}$@{PATH:+:@}/sbin"; +@} +@end group +@end example + @item @var{name}=+@var{value} Retain variable @var{name} and prepend @var{value} to its existing value. If no such variable is present in the environment, it is created and @var{value} is assigned to it. However, if @var{value} ends with a punctuation character, this character is removed from it before assignment. -@end table -@end deffn -@deffn {Config: component} max-instances @var{n} -Sets the maximum number of simultaneously running instances of this -component. +In modern syntax, use shell variable references, e.g. instead of +doing + +@example +env PATH=+/sbin: +@end example + +@noindent +use + +@example +@group +env @{ + set "PATH=/sbin$@{PATH:+:@}$PATH"; +@} +@end group +@end example + +@end table @end deffn @node Actions Before Startup @@ -1186,6 +1373,9 @@ additional variables: @item PIES_VERSION The @command{pies} version number (@value{VERSION}). +@item PIES_MASTER_PID +PID of the master @command{pies} process. + @item PIES_COMPONENT Tag of the terminated component (@pxref{Component Statement, tag}). |