setenv() — Add, delete, and change environment variables
Standards
Standards / Extensions | C or C++ | Dependencies |
---|---|---|
POSIX.1a
Single UNIX Specification, Version 3 Language Environment® |
both |
Format
#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)
General description
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.
- Nonzero
- Change the existing entry. If var_name has already been defined and exists in the environment variable table, its value will be updated with new_value. If var_name was previously undefined, it will be appended to the table.
- 0
- Do not change the existing entry.
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.
- The value of the change_flag is irrelevant
if new_value
=NULL
. - You should not define environment variables that begin with '_BPXK_'
since they might conflict with variable names defined by z/OS® UNIX services.
setenv() uses the BPX1ENV callable service to
pass environment variables that begin with '_BPXK_' to the kernel.
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.
- Code is compiled with the compiler option LANGLV(ANSI), uses
#include <env.h>
, and has the POSIX feature tests turned on. - Code is compiled with
LONGNAME
and prelinked with the OMVS option.
Returned value
If successful, setenv() returns 0.
If unsuccessful, setenv() returns -1 and sets errno to indicate the type of failure that occurred.
- Error Code
- Description
- EINVAL
-
The name argument is a null pointer, points to an empty string, or points to a string containing an '=' character.
Note: Starting with z/OS V1.9, environment variable _EDC_SUSV3 can be used to control the behavior of setenv() with respect to setting EINVAL when var_name is a null pointer, points to an empty string or points to a string containing an '=' character. By default, setenv() will not set EINVAL for these conditions. When _EDC_SUSV3 is set to 1, setenv() will set errno to EINVAL if one of these conditions is true. - ENOMEM
- Insufficient memory was available to add a variable or its value to the environment.
Example
/* 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
Related information
- See the topic about using environment variables in z/OS XL C/C++ Programming Guide.
- stdlib.h — Standard library functions
- clearenv() — Clear environment variables
- getenv() — Get value of environment variables
- __getenv() — Get an environment variable
- putenv() — Change or add an environment variable
- system() — Execute a command