putenv() — Change or add an environment variable
Standards
Standards / Extensions | C or C++ | Dependencies |
---|---|---|
XPG4 |
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.
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.
Related information
- See the topic about C/370™ environmental variables in z/OS XL C/C++ Programming Guide
- stdlib.h
- clearenv() — Clear environment variables
- getenv() — Get value of environment variables
- __getenv() — Get an environment variable
- setenv() — Add, delete, and change environment variables