A.17 The Package Environment_Variables
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.
Static Semantics
The library package
Environment_Variables has the following declaration:
package Ada.Environment_Variables
with Preelaborate, Nonblocking, Global =>
in out synchronized is
function Value (Name :
in String)
return String;
function Value (Name :
in String; Default :
in String)
return String;
function Exists (Name :
in String)
return Boolean;
procedure Set (Name :
in String; Value :
in String);
procedure Clear (Name :
in String);
procedure Clear;
procedure Iterate
(Process :
not null access procedure (Name, Value :
in String))
with Allows_Exit;
end Ada.Environment_Variables;
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.
It is implementation
defined whether there exist values for which the call Set(Name, Value)
has the same effect as Clear (Name).
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
It
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
Making 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
An implementation shall document how the operations
of this package behave if environment variables are changed by external
mechanisms (for instance, calling operating system services).
Implementation Permissions
An 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
If the execution environment supports subprocesses,
the currently defined 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.
Ada 2005 and 2012 Editions sponsored in part by Ada-Europe
