aboutsummaryrefslogtreecommitdiff
path: root/doc
diff options
context:
space:
mode:
authorSergey Poznyakoff <gray@gnu.org>2019-06-03 13:17:13 +0300
committerSergey Poznyakoff <gray@gnu.org>2019-06-03 13:41:34 +0300
commitf50a208f9df348cede2ba50b4f435351d8d3f19e (patch)
treec596fdf237b17713ab56c0269cdb1d339e306941 /doc
parent8004bbaa1b31b14dd4c4d3886b5f57b103bf7405 (diff)
downloadpies-f50a208f9df348cede2ba50b4f435351d8d3f19e.tar.gz
pies-f50a208f9df348cede2ba50b4f435351d8d3f19e.tar.bz2
Finish the env re-implementation
* NEWS: Document the "env" statement and the PIES_MASTER_PID environment variable. Version 1.3.91 * configure.ac: Version 1.3.91 * doc/pies.texi: Document the new "env" statement syntax. Provide instructions on how to convert legacy "env" statement to the new form. * lib/envop.c (environ_unset): Take reference value as argument. If supplied, unset the variable only if its value matches the reference one. * lib/envop.h (environ_unset): Change proto. * src/pies.c (parse_legacy_env): Minor changes. (_cb_env_unset): Allow to specify value. * src/progman.c (run_command): Define PIES_MASTER_PID. * tests/env.at: Check the legacy env syntax. * tests/envop.at: Additional checks.
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
@@ -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

Return to:

Send suggestions and report system problems to the System administrator.