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 | |||
@@ -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 | |||
1038 | than @samp{777}. The default umask is inherited at startup. | 1040 | than @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} |
1044 | Sets the maximum number of simultaneously running instances of this | ||
1045 | component. | ||
1046 | @end deffn | ||
1047 | |||
1048 | @node Environment | ||
1049 | @subsection Environment | ||
1050 | Normally all components inherit the environment of the master | ||
1051 | @command{pies} process. You can modify this environment using | ||
1052 | the @code{env} statement. It has two variants: @dfn{compound} and @dfn{legacy}. | ||
1053 | The legacy one-line statement was used in @command{pies} versions | ||
1054 | up to 1.3 and is still retained for backward compatibility. It is | ||
1055 | described in @ref{env legacy syntax}. This subsection describes the | ||
1056 | modern compount syntax. | ||
1057 | |||
1058 | @deffn {Config: component} env @{ ... @} | ||
1059 | The compound @code{env} statement has the following syntax: | ||
1060 | |||
1061 | @example | ||
1062 | @group | ||
1063 | env @{ | ||
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 | |||
1073 | Statements inside the @code{env} block define operations that | ||
1074 | modify the environment. The @code{clear} and @code{keep} statements | ||
1075 | are executed first. Then, the @code{set} and @code{unset} statements | ||
1076 | are applied in the order of their appearance in the configuration. | ||
1077 | |||
1078 | @deffn {env} clear @var{bool} | ||
1079 | If @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} | ||
1082 | statement is always executed first. | ||
1083 | @end deffn | ||
1084 | |||
1085 | @deffn {env} keep @var{pattern} | ||
1086 | Declares variables matching @var{pattern} (a globbing pattern) as | ||
1087 | exempt from clearing. This statement implies @code{clear}. | ||
1088 | |||
1089 | For example, the following configuration fragment removes from the | ||
1090 | environment all variables except @samp{HOME}, @samp{USER}, | ||
1091 | @samp{PATH}, and variables beginning with @samp{LC_}: | ||
1092 | |||
1093 | @example | ||
1094 | @group | ||
1095 | env @{ | ||
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}" | ||
1107 | Retains the variable @var{name}, if it has the given value. Note, that | ||
1108 | the argument must be quoted. | ||
1109 | @end deffn | ||
1110 | |||
1111 | @deffn {env} set "@var{name}=@var{value}" | ||
1112 | Assigns @var{value} to environment variable @var{name}. The value is | ||
1113 | subject to @dfn{variable expansion} using the same syntax as in shell. | ||
1114 | The @code{set} and @code{unset} (see below) statements are executed in | ||
1115 | order of their appearance. For example | ||
1116 | |||
1117 | @example | ||
1118 | @group | ||
1119 | env @{ | ||
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} | ||
1128 | Unset environment variables matching @var{pattern}. The following | ||
1129 | will unset the @env{LOGIN} variable: | ||
1130 | |||
1131 | @example | ||
1132 | unset LOGIN; | ||
1133 | @end example | ||
1134 | |||
1135 | @noindent | ||
1136 | The following will unset all variables starting with @samp{LD_}: | ||
1137 | |||
1138 | @example | ||
1139 | unset "LD_*"; | ||
1140 | @end example | ||
1141 | |||
1142 | @noindent | ||
1143 | Notice, 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. | ||
1152 | Up to version 1.3 @command{pies} implemented the one-line variant of | ||
1153 | the @code{env} statement. The use of this legacy syntax is | ||
1154 | discouraged. It is supported for backward compatibility only and will | ||
1155 | be removed in future versions. This subsection describes the legacy | ||
1156 | syntax. | ||
1157 | |||
1158 | @deffn {legacy syntax} env @var{args} | ||
1042 | Set program environment. | 1159 | Set program environment. |
1043 | 1160 | ||
1044 | Arguments are a whitespace-delimited list of specifiers. The | 1161 | Arguments are a whitespace-delimited list of specifiers. The |
@@ -1049,17 +1166,63 @@ following specifiers are understood: | |||
1049 | Clear the environment. This is understood only when used as a first | 1166 | Clear the environment. This is understood only when used as a first |
1050 | word in @var{args}. | 1167 | word in @var{args}. |
1051 | 1168 | ||
1169 | The modern syntax equivalent is: | ||
1170 | |||
1171 | @example | ||
1172 | @group | ||
1173 | env @{ | ||
1174 | clear yes; | ||
1175 | @} | ||
1176 | @end group | ||
1177 | @end example | ||
1178 | |||
1052 | @item -@var{name} | 1179 | @item -@var{name} |
1053 | Unset the environment variable @var{name}. | 1180 | Unset the environment variable @var{name}. The modern syntax |
1181 | equivalent is | ||
1182 | |||
1183 | @example | ||
1184 | @group | ||
1185 | env @{ | ||
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} |
1056 | Unset the environment variable @var{name} only if its value is @var{val}. | 1192 | Unset the environment variable @var{name} only if its value is @var{val}. |
1193 | The modern syntax equivalent is: | ||
1194 | |||
1195 | @example | ||
1196 | @group | ||
1197 | env @{ | ||
1198 | unset "@var{name}=@var{val}"; | ||
1199 | @} | ||
1200 | @end group | ||
1201 | @end example | ||
1057 | 1202 | ||
1058 | @item @var{name} | 1203 | @item @var{name} |
1059 | Retain the environment variable @var{name}. | 1204 | Retain the environment variable @var{name}. The modern syntax |
1205 | equivalent is | ||
1206 | |||
1207 | @example | ||
1208 | @group | ||
1209 | env @{ | ||
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} |
1062 | Define environment variable @var{name} to have given @var{value}. | 1216 | Define environment variable @var{name} to have given @var{value}. The |
1217 | modern syntax equivalent is: | ||
1218 | |||
1219 | @example | ||
1220 | @group | ||
1221 | env @{ | ||
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} |
1065 | Retain variable @var{name} and append @var{value} to its existing | 1228 | Retain 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 | |||
1077 | to it. Otherwise, it will be created and @samp{/sbin} will be | 1240 | to it. Otherwise, it will be created and @samp{/sbin} will be |
1078 | assigned to it. | 1241 | assigned to it. |
1079 | 1242 | ||
1243 | In modern syntax, use shell variable references, e.g.: | ||
1244 | |||
1245 | @example | ||