| Standards / Extensions | C or C++ | Dependencies |
|---|---|---|
POSIX.1a |
both |
#define _POSIX1_SOURCE 2
#include <env.h>
int setenv(const char *var_name, const char *new_value, int change_flag)#define _UNIX03_SOURCE
#include <stdlib.h>
int setenv(const char *var_name, const char *new_value, int change_flag)#include <stdlib.h>
int setenv(const char *var_name, const char *new_value, int change_flag)Adds, changes, and deletes environment variables.
To avoid infringing on the user's name space, the non-POSIX version of this function has two names. One name is prefixed with two underscore characters, and one name is not. The name without the prefix underscore characters is exposed only when you use LANGLVL(EXTENDED).
To use this function, you must either invoke the function using its external entry point name (that is, the name that begins with two underscore characters), or compile with LANGLVL(EXTENDED). When you use LANGLVL(EXTENDED) any relevant information in the header is also exposed.
var_name is a pointer to a character string that contains the name of the environment variable to be added, changed, or deleted. If setenv() is called with var_name containing an equal sign ('='), setenv() will fail, and errno will be set to indicate that an invalid argument was passed to the function.
new_value is a pointer to a character string that contains the value of the environment variable named in var_name. If new_value is a NULL pointer, it indicates that all occurrences of the environment variable named in var_name be deleted.
If var_name has already been defined and exists in the environment variable table, its value will not be updated with new_value. However, if var_name was previously undefined, it will be appended to the table.
Also, do not use '_EDC_' and '_CEE_'. They are used by the runtime library and the Language Environment.
Environment variables set with the setenv() function will only exist for the life of the program, and are not saved before program termination. Other ways to set environment variables are found in “Using Environment Variables” in z/OS XL C/C++ Programming Guide.
If successful, setenv() returns 0.
If unsuccessful, setenv() returns -1 and sets errno to indicate the type of failure that occurred.
The name argument is a null pointer, points to an empty string, or points to a string containing an '=' character.
⁄* CELEBS03
This example (program 1) sets the environment variable
_EDC_ANSI_OPEN_DEFAULT.
A child program (program 2) is then initiated via a system
call.
The example illustrates that environment variables are
propagated forward to a child program, but not backward to
the parent.
*⁄
#include <stdio.h>
#include <stdlib.h>
int main(void)
{
char *x;
⁄* set environment variable _EDC_ANSI_OPEN_DEFAULT to "Y" *⁄
setenv("_EDC_ANSI_OPEN_DEFAULT","Y",1);
⁄* set x to the current value of the _EDC_ANSI_OPEN_DEFAULT*⁄
x = getenv("_EDC_ANSI_OPEN_DEFAULT");
printf("program1 _EDC_ANSI_OPEN_DEFAULT = %s\n",
(x != NULL) ? x : "undefined");
⁄* call the child program *⁄
system("program2");
⁄* set x to the current value of the _EDC_ANSI_OPEN_DEFAULT*⁄
x = getenv("_EDC_ANSI_OPEN_DEFAULT");
printf("program1 _EDC_ANSI_OPEN_DEFAULT = %s\n",
(x != NULL) ? x : "undefined");
} ⁄* CELEBS04
Program 2:
A child program of CELEBS03, which is initiated via a system call.
*⁄
#include <stdio.h>
#include <stdlib.h>
int main(void)
{
char *x;
⁄* set x to the current value of the _EDC_ANSI_OPEN_DEFAULT*⁄
x = getenv("_EDC_ANSI_OPEN_DEFAULT");
printf("program2 _EDC_ANSI_OPEN_DEFAULT = %s\n",
(x != NULL) ? x : "undefined");
⁄* clear the Environment Variables Table *⁄
setenv("_EDC_ANSI_OPEN_DEFAULT", NULL, 1);
⁄* set x to the current value of the _EDC_ANSI_OPEN_DEFAULT*⁄
x = getenv("_EDC_ANSI_OPEN_DEFAULT");
printf("program2 _EDC_ANSI_OPEN_DEFAULT = %s\n",
(x != NULL) ? x : "undefined");
} program1 _EDC_ANSI_OPEN_DEFAULT = Y
program2 _EDC_ANSI_OPEN_DEFAULT = Y
program2 _EDC_ANSI_OPEN_DEFAULT = undefined
program1 _EDC_ANSI_OPEN_DEFAULT = Y