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
@@ -122,6 +122,7 @@ Component Statement
122* Prerequisites:: 122* Prerequisites::
123* Component Privileges:: 123* Component Privileges::
124* Resources:: 124* Resources::
125* Environment::
125* Actions Before Startup:: 126* Actions Before Startup::
126* Exit Actions:: 127* Exit Actions::
127* Output Redirectors:: 128* Output Redirectors::
@@ -712,7 +713,7 @@ compatibility with the @sc{c} preprocessor.
712@end table 713@end table
713 714
714@node Component Statement 715@node Component Statement
715@section Component Statement 716@section The @code{component} Statement
716@kwindex component 717@kwindex component
717 718
718@deffn {Config} component 719@deffn {Config} component
@@ -937,6 +938,7 @@ substatements.
937* Prerequisites:: 938* Prerequisites::
938* Component Privileges:: 939* Component Privileges::
939* Resources:: 940* Resources::
941* Environment::
940* Actions Before Startup:: 942* Actions Before Startup::
941* Exit Actions:: 943* Exit Actions::
942* Output Redirectors:: 944* Output Redirectors::
@@ -1038,7 +1040,122 @@ Set the umask. The @var{number} must be an octal value not greater
1038than @samp{777}. The default umask is inherited at startup. 1040than @samp{777}. The default umask is inherited at startup.
1039@end deffn 1041@end deffn
1040 1042
1041@deffn {Config: component} env @var{args} 1043@deffn {Config: component} max-instances @var{n}
1044Sets the maximum number of simultaneously running instances of this
1045component.
1046@end deffn
1047
1048@node Environment
1049@subsection Environment
1050Normally all components inherit the environment of the master
1051@command{pies} process. You can modify this environment using
1052the @code{env} statement. It has two variants: @dfn{compound} and @dfn{legacy}.
1053The legacy one-line statement was used in @command{pies} versions
1054up to 1.3 and is still retained for backward compatibility. It is
1055described in @ref{env legacy syntax}. This subsection describes the
1056modern compount syntax.
1057
1058@deffn {Config: component} env @{ ... @}
1059The compound @code{env} statement has the following syntax:
1060
1061@example
1062@group
1063env @{
1064 clear @var{bool};
1065 keep @var{pattern};
1066 set "@var{name}=@var{value}";
1067 unset @var{pattern};
1068@}
1069@end group
1070@end example
1071@end deffn
1072
1073Statements inside the @code{env} block define operations that
1074modify the environment. The @code{clear} and @code{keep} statements
1075are executed first. Then, the @code{set} and @code{unset} statements
1076are applied in the order of their appearance in the configuration.
1077
1078@deffn {env} clear @var{bool}
1079If @var{bool} is @samp{yes}, all environment variables will be cleared
1080(unset). The resulting environment will be empty, unless one or more
1081@code{keep} statements are also given (see below). The @code{clear}
1082statement is always executed first.
1083@end deffn
1084
1085@deffn {env} keep @var{pattern}
1086Declares variables matching @var{pattern} (a globbing pattern) as
1087exempt from clearing. This statement implies @code{clear}.
1088
1089For example, the following configuration fragment removes from the
1090environment all variables except @samp{HOME}, @samp{USER},
1091@samp{PATH}, and variables beginning with @samp{LC_}:
1092
1093@example
1094@group
1095env @{
1096 clear yes;
1097 keep HOME;
1098 keep USER;
1099 keep PATH;
1100 keep "LC_*";
1101@}
1102@end group
1103@end example
1104@end deffn
1105
1106@deffn {env} keep "@var{name}=@var{value}"
1107Retains the variable @var{name}, if it has the given value. Note, that
1108the argument must be quoted.
1109@end deffn
1110
1111@deffn {env} set "@var{name}=@var{value}"
1112Assigns @var{value} to environment variable @var{name}. The value is
1113subject to @dfn{variable expansion} using the same syntax as in shell.
1114The @code{set} and @code{unset} (see below) statements are executed in
1115order of their appearance. For example
1116
1117@example
1118@group
1119env @{
1120 set "MYLIB=$HOME/lib";
1121 set "LD_LIBRARY_PATH=$LD_LIBRARY_PATH$@{LD_LIBRARY_PATH:+:@}$MYLIB";
1122@}
1123@end group
1124@end example
1125@end deffn
1126
1127@deffn {env} unset @var{pattern}
1128Unset environment variables matching @var{pattern}. The following
1129will unset the @env{LOGIN} variable:
1130
1131@example
1132unset LOGIN;
1133@end example
1134
1135@noindent
1136The following will unset all variables starting with @samp{LD_}:
1137
1138@example
1139unset "LD_*";
1140@end example
1141
1142@noindent
1143Notice, that patterns containing wildcard characters must be quoted.
1144@end deffn
1145
1146@menu
1147* env legacy syntax::
1148@end menu
1149
1150@node env legacy syntax
1151@subsubsection @code{env}: legacy syntax.
1152Up to version 1.3 @command{pies} implemented the one-line variant of
1153the @code{env} statement. The use of this legacy syntax is
1154discouraged. It is supported for backward compatibility only and will
1155be removed in future versions. This subsection describes the legacy
1156syntax.
1157
1158@deffn {legacy syntax} env @var{args}
1042Set program environment. 1159Set program environment.
1043 1160
1044Arguments are a whitespace-delimited list of specifiers. The 1161Arguments are a whitespace-delimited list of specifiers. The
@@ -1049,17 +1166,63 @@ following specifiers are understood:
1049Clear the environment. This is understood only when used as a first 1166Clear the environment. This is understood only when used as a first
1050word in @var{args}. 1167word in @var{args}.
1051 1168
1169The modern syntax equivalent is:
1170
1171@example
1172@group
1173env @{
1174 clear yes;
1175@}
1176@end group
1177@end example
1178
1052@item -@var{name} 1179@item -@var{name}
1053Unset the environment variable @var{name}. 1180Unset the environment variable @var{name}. The modern syntax
1181equivalent is
1182
1183@example
1184@group
1185env @{
1186 unset @var{name};
1187@}
1188@end group
1189@end example
1054 1190
1055@item -@var{name}=@var{val} 1191@item -@var{name}=@var{val}
1056Unset the environment variable @var{name} only if its value is @var{val}. 1192Unset the environment variable @var{name} only if its value is @var{val}.
1193The modern syntax equivalent is:
1194
1195@example
1196@group
1197env @{
1198 unset "@var{name}=@var{val}";
1199@}
1200@end group
1201@end example
1057 1202
1058@item @var{name} 1203@item @var{name}
1059Retain the environment variable @var{name}. 1204Retain the environment variable @var{name}. The modern syntax
1205equivalent is
1206
1207@example
1208@group
1209env @{
1210 keep @var{name};
1211@}
1212@end group
1213@end example
1060 1214
1061@item @var{name}=@var{value} 1215@item @var{name}=@var{value}
1062Define environment variable @var{name} to have given @var{value}. 1216Define environment variable @var{name} to have given @var{value}. The
1217modern syntax equivalent is:
1218
1219@example
1220@group
1221env @{
1222 keep "@var{name}=@var{value}";
1223@}
1224@end group
1225@end example
1063 1226
1064@item @var{name}+=@var{value} 1227@item @var{name}+=@var{value}
1065Retain variable @var{name} and append @var{value} to its existing 1228Retain 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
1077to it. Otherwise, it will be created and @samp{/sbin} will be 1240to it. Otherwise, it will be created and @samp{/sbin} will be
1078assigned to it. 1241assigned to it.
1079 1242
1243In modern syntax, use shell variable references, e.g.:
1244
1245@example