A.17 The Package Environment_Variables
This Reference Manual output has not been verified, and may contain omissions or errors. Report any problems on the tracking issue
The package Environment_Variables allows a program to read or modify environment variables. Environment variables are name-value pairs, where both the name and value are strings. The definition of what constitutes an environment variable, and the meaning of the name and value, are implementation defined.
The definition and meaning of an environment variable.
Static Semantics
2/2The library package Environment_Variables has the following declaration:
package Ada.Environment_Variables
with Preelaborate, Nonblocking, Global => in out synchronized is
4/2
function Value (Name : in String) return String;
4.1/3
function Value (Name : in String; Default : in String) return String;
5/2
function Exists (Name : in String) return Boolean;
6/2
procedure Set (Name : in String; Value : in String);
7/2
procedure Clear (Name : in String);
procedure Clear;
8/5
procedure Iterate
(Process : not null access procedure (Name, Value : in String))
with Allows_Exit;
9/2
end Ada.Environment_Variables;
10/2
function Value (Name : in String) return String;
If the external execution environment supports environment variables, then Value returns the value of the environment variable with the given name. If no environment variable with the given name exists, then Constraint_Error is propagated. If the execution environment does not support environment variables, then Program_Error is propagated.
function Value (Name : in String; Default : in String) return String;
If the external execution environment supports environment variables and an environment variable with the given name currently exists, then Value returns its value; otherwise, it returns Default.
function Exists (Name : in String) return Boolean;
If the external execution environment supports environment variables and an environment variable with the given name currently exists, then Exists returns True; otherwise, it returns False.
procedure Set (Name : in String; Value : in String);
If the external execution environment supports environment variables, then Set first clears any existing environment variable with the given name, and then defines a single new environment variable with the given name and value. Otherwise, Program_Error is propagated.
If implementation-defined circumstances prohibit the definition of an environment variable with the given name and value, then Constraint_Error is propagated.
The circumstances where an environment variable cannot be defined.
It is implementation defined whether there exist values for which the call Set(Name, Value) has the same effect as Clear (Name).
Environment names for which Set has the effect of Clear.
procedure Clear (Name : in String);
If the external execution environment supports environment variables, then Clear deletes all existing environment variables with the given name. Otherwise, Program_Error is propagated.
procedure Clear;
If the external execution environment supports environment variables, then Clear deletes all existing environment variables. Otherwise, Program_Error is propagated.
procedure Iterate
(Process : not null access procedure (Name, Value : in String))
with Allows_Exit;
If the external execution environment supports environment variables, then Iterate calls the subprogram designated by Process for each existing environment variable, passing the name and value of that environment variable. Otherwise, Program_Error is propagated.
If several environment variables exist that have the same name, Process is called once for each such variable.
Bounded (Run-Time) Errors
25/2It is a bounded error to call Value if more than one environment variable exists with the given name; the possible outcomes are that:
- one of the values is returned, and that same value is returned in subsequent calls in the absence of changes to the environment; or
- Program_Error is propagated.
Erroneous Execution
28/2Making calls to the procedures Set or Clear concurrently with calls to any subprogram of package Environment_Variables, or to any instantiation of Iterate, results in erroneous execution.
Making calls to the procedures Set or Clear in the actual subprogram corresponding to the Process parameter of Iterate results in erroneous execution.
Documentation Requirements
30/2An implementation shall document how the operations of this package behave if environment variables are changed by external mechanisms (for instance, calling operating system services).
Documentation Requirement: The behavior of package Environment_Variables when environment variables are changed by external mechanisms.
Implementation Permissions
31/2An implementation running on a system that does not support environment variables is permitted to define the operations of package Environment_Variables with the semantics corresponding to the case where the external execution environment does support environment variables. In this case, it shall provide a mechanism to initialize a nonempty set of environment variables prior to the execution of a partition.
Implementation Advice
32/2If the execution environment supports subprocesses, the currently defined environment variables should be used to initialize the environment variables of a subprocess.
If the execution environment supports subprocesses, the current environment variables should be used to initialize the environment variables of a subprocess.
Changes to the environment variables made outside the control of this package should be reflected immediately in the effect of the operations of this package. Changes to the environment variables made using this package should be reflected immediately in the external execution environment. This package should not perform any buffering of the environment variables.
Changes to the environment variables made outside the control of Environment_Variables should be reflected immediately.
Extensions to Ada 95
Incompatibilities With Ada 2005
A new overloaded function Value is added to Environment_Variables. If Environment_Variables is referenced in a use_clause, and an entity E with the name Value is defined in a package that is also referenced in a use_clause, the entity E may no longer be use-visible, resulting in errors. This should be rare and is easily fixed if it does occur.
A.17.1 The Packages Wide_Environment_Variables and Wide_Wide_Environment_Variables
1/5The packages Wide_Environment_Variables and Wide_Wide_Environment_Variables allow a program to read or modify environment variables.
Static Semantics
2/5The specification of package Wide_Environment_Variables is the same as for Environment_Variables, except that each occurrence of String is replaced by Wide_String.
The specification of package Wide_Wide_Environment_Variables is the same as for Environment_Variables, except that each occurrence of String is replaced by Wide_Wide_String.