diff options
author | Sergey Poznyakoff <gray@gnu.org> | 2019-06-03 13:17:13 +0300 |
---|---|---|
committer | Sergey Poznyakoff <gray@gnu.org> | 2019-06-03 13:41:34 +0300 |
commit | f50a208f9df348cede2ba50b4f435351d8d3f19e (patch) | |
tree | c596fdf237b17713ab56c0269cdb1d339e306941 /doc | |
parent | 8004bbaa1b31b14dd4c4d3886b5f57b103bf7405 (diff) | |
download | pies-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.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 @@ -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. |