diff options
Diffstat (limited to 'doc/pies.texi')
-rw-r--r-- | doc/pies.texi | 212 |
1 files changed, 201 insertions, 11 deletions
diff --git a/doc/pies.texi b/doc/pies.texi index b77a40c..ccb9f0e 100644 --- a/doc/pies.texi +++ b/doc/pies.texi @@ -124,2 +124,3 @@ Component Statement * Resources:: +* Environment:: * Actions Before Startup:: @@ -714,3 +715,3 @@ compatibility with the @sc{c} preprocessor. @node Component Statement -@section Component Statement +@section The @code{component} Statement @kwindex component @@ -939,2 +940,3 @@ substatements. * Resources:: +* Environment:: * Actions Before Startup:: @@ -1040,3 +1042,118 @@ than @samp{777}. The default umask is inherited at startup. -@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. @@ -1051,4 +1168,23 @@ 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 @@ -1056,8 +1192,35 @@ Unset the environment variable @var{name}. 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 @@ -1079,2 +1242,12 @@ 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} @@ -1084,9 +1257,23 @@ 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 +before assignment. -@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 @@ -1188,2 +1375,5 @@ The @command{pies} version number (@value{VERSION}). +@item PIES_MASTER_PID +PID of the master @command{pies} process. + @item PIES_COMPONENT |