Standards
| Standards / Extensions |
C or C++ |
Dependencies |
|---|
| z/OS® UNIX |
both |
|
Format
#include <stdlib.h>
char *__getenv(const char *varname);
General
description
__getenv() returns a unique character pointer for each environmental
variable. For single-threaded applications, this eliminates the need
to copy the string returned by previous __getenv() calls.
This function should not be used by multithreaded applications.
Updates to the environmental variable on another thread may invalidate
the address returned by __getenv() before the application copies the
returned value.
The format of an environment variable is made up of three parts
that are combined to form:
name=value
Where:
- The first part, name, is a character string that represents
the name of the environment variable. It is this part of the environment
variable that __getenv() tries to match with varname.
- The second part, =, is a separator character (since the
equal sign is used as a separator character it cannot appear in the name).
- The third part, value, is a NULL-terminated character
string that represents the value that the environment variable, name,
is set to. This is the part of the environment variable that __getenv()
returns a pointer to.
There are several ways to establish a set of environment variables.
- Set at program initialization time from the Language Environment® runtime
option ENVAR.
- Set at program initialization time from a data set.
- If the program was invoked with a system() call, they can be inherited
from the calling enclave.
- In the z/OS UNIX environment they can also be inherited from the
parent process if the program was invoked with one of the exec functions.
- During the running of a program they can be set with the setenv()
function or the putenv() function.
For a list of the environment variables that z/OS UNIX services support,
see the topic “Using
Environment Variables” in z/OS XL C/C++ Programming Guide.
Special behavior for POSIX: Under
POSIX, the value of the char **environ pointer is honored
and used by getenv(). You can declare and use this pointer. Under
POSIX(OFF) this is not the case: the table start cannot be modified.
Note: The __getenv() function has a dependency on the
level of the Enhanced ASCII Extensions. See
Enhanced ASCII support for
details.
Returned value
If successful, __getenv() returns a pointer to the string containing
the value of the environment variable specified by varname.
If unsuccessful, __getenv() returns a NULL pointer. The returned
value is NULL if the given variable is not currently defined or if
the system does not support environment variables.