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

POSIX - C only:
#define _POSIX1_SOURCE 2
#include <env.h>

int setenv(const char *var_name, const char *new_value, int change_flag)
Single UNIX Specification, Version 3:
#define _UNIX03_SOURCE
#include <stdlib.h>

int setenv(const char *var_name, const char *new_value, int change_flag)
Non-POSIX:
#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.

change_flag is a flag that can take any integer value:
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.

Notes:
  1. The value of the change_flag is irrelevant if new_value=NULL.
  2. 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.

Special behavior for POSIX C: Under POSIX, setenv() is available if one of the following is true:
  • 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
/* 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
/* 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");                                           
}                                                                               
Output
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