Standards
| Standards / Extensions |
C or C++ |
Dependencies |
|---|
XPG4
XPG4.2
Single UNIX Specification, Version 3
|
both |
|
Format
#define _XOPEN_SOURCE
#include <stdlib.h>
int putenv(char *envvar);
General description
Adds a new
environment variable or changes the value of an existing one. The
argument
envvar is a pointer to a NULL-terminated
character string that should be of the 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 putenv() will use when
it searches the array of environment variable to determine whether
to add or change this environment variable.
- 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,
will be set to.
putenv() is a simplified form of setenv() and is equivalent
to
setenv(name, value, 1)
Note: Starting
with, z/OS® V1R2, the storage
used to define the environment variable pointed to by envvar is
added to the array of environment variables. Previously, the system
copied the string into system allocated storage. A new environment
variable, _EDC_PUTENV_COPY, will allow the previous behavior to continue
if set to YES. If _EDC_PUTENV_COPY is not set or is set to any other
value the new behavior will take place.
Special behavior for POSIX C: You can use
the external variable **environ (defined
as extern char **environ)
to access the array of pointers to environment variables.
Returned value
If successful, putenv()
returns 0.
If unsuccessful, putenv() returns -1 and sets errno
to one of the following values:
- Error Code
- Description
- ENOMEM
- Insufficient memory was available.
Special behavior for z/OS UNIX Services: - EINVAL
- The environment variable pointed to by the argument envvar does
not follow the prescribed format. The equal sign (=) separating the
environment variable name from the value was not found.