A.17 The Package Environment_Variables
{
AI95-00370-01}
{environment variable} 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.
Implementation defined: The definition
and meaning of an environment variable.
Static Semantics
{
AI95-00370-01}
The library package Environment_Variables has the following declaration:
package Ada.Environment_Variables
is
pragma Preelaborate(Environment_Variables);
function Value (Name :
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));
end Ada.Environment_Variables;
function Value (Name : in String) return String;
{
AI95-00370-01}
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 Exists (Name : in String) return Boolean;
{
AI95-00370-01}
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);
{
AI95-00370-01}
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.
Implementation defined: 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).
Implementation defined: Environment names
for which Set has the effect of Clear.
procedure Clear (Name : in String);
{
AI95-00370-01}
If the external execution environment supports environment variables,
then Clear deletes all existing environment variable with the given name.
Otherwise Program_Error is propagated.
procedure Clear;
{
AI95-00370-01}
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));
{
AI95-00370-01}
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
{
AI95-00370-01}
{bounded error (cause) [partial]}
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
{
AI95-00370-01}
{erroneous execution (cause) [partial]}
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
{
AI95-00370-01}
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).
Documentation Requirement: The behavior
of package Environment_Variables when environment variables are changed
by external mechanisms.
Implementation Permissions
{
AI95-00370-01}
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
{
AI95-00370-01}
If the execution environment supports subprocesses, the currently defined
environment variables should be used to initialize the environment variables
of a subprocess.
Implementation Advice: 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.
Implementation Advice: Changes to the
environment variables made outside the control of Environment_Variables
should be reflected immediately.
Extensions to Ada 95
{
AI95-00370-01}
{
extensions to Ada 95}
Package Environment_Variables
is new.
Sponsored by Ada-Europe