aboutsummaryrefslogtreecommitdiff
path: root/doc
diff options
context:
space:
mode:
Diffstat (limited to 'doc')
-rw-r--r--doc/pies.texi212
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
@@ -119,12 +119,13 @@ Configuration File Syntax
Component Statement
* Prerequisites::
* Component Privileges::
* Resources::
+* Environment::
* Actions Before Startup::
* Exit Actions::
* Output Redirectors::
* Inetd-Style Components::
* Meta1-Style Components::
* Visibility::
@@ -709,13 +710,13 @@ If the latter is absent, the remembered file name does not change.
@item # @var{num} "@var{file}"
This is a special form of @code{#line} statement, understood for
compatibility with the @sc{c} preprocessor.
@end table
@node Component Statement
-@section Component Statement
+@section The @code{component} Statement
@kwindex component
@deffn {Config} component
The @code{component} statement defines a new component:
@end deffn
@@ -934,12 +935,13 @@ The following subsections describe the rest of @samp{component}
substatements.
@menu
* Prerequisites::
* Component Privileges::
* Resources::
+* Environment::
* Actions Before Startup::
* Exit Actions::
* Output Redirectors::
* Inetd-Style Components::
* Meta1-Style Components::
* Visibility::
@@ -1035,34 +1037,195 @@ in version @value{VERSION}.
@deffn {Config: component} umask @var{number}
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
following specifiers are understood:
@table @asis
@item - (a dash)
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
value. If no such variable is present in the environment, it is
created and @var{value} is assigned to it. However, if @var{value}
begins with a punctuation character, this character is removed from it
@@ -1074,24 +1237,48 @@ PATH+=:/sbin
@end example
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
+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
@node Actions Before Startup
@subsection Actions Before Startup
The statements described in this subsection specify actions to perform
@@ -1183,12 +1370,15 @@ environment from the main @command{pies} process with the following
additional variables:
@table @env
@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}).
@item PIES_PID
PID of the terminated component.

Return to:

Send suggestions and report system problems to the System administrator.