setenv(3C)

NAME

setenv(), unsetenv() — add, update or remove an environment variable

SYNOPSIS

#include <stdlib.h> 

int setenv(const char *envname, const char *envval, int overwrite); 

int unsetenv(const char *envname); 

Parameters

envname: Points to a string containing the name of an environment variable to be added or altered. This should not be a NULL pointer or null string, and the string should not contain an equal (=) character.
envval: Points to a string containing the value to be set for the variable envname.
overwrite: Indicates whether to overwrite the value of envname variable or not, if it already exists. Expected values are non-zero and zero. If the environment variable does not exist in the environment, then the value of this variable is ignored.

DESCRIPTION

setenv() and unsetenv() functions update the environment of the calling process.

If envname does not exist, the setenv() function ignores the value of overwrite and adds the variable envname to the environment with the value envval. If envname exists and overwrite is non-zero, then the variable envname is updated with the new value envval. If envname exists and overwrite is zero, then the variable is not updated, and the function is considered to have completed successfully.

The unsetenv() function deletes the variable envname from the environment, if it exists. If the envname variable does not exist in the current environment, the environment is unchanged, and the function is considered to have completed successfully.

If the application modifies environ or the pointers to which it points, the behavior of setenv() and unsetenv() is undefined.

EXTERNAL INFLUENCES

Locale

The LC_CTYPE category determines the interpretation of characters in string as single- and/or multi-byte characters.

International Code Set Support

Single- and multi-byte character code sets are supported.

RETURN VALUE

The setenv() and unsetenv() functions return zero on success; otherwise they return -1 and set errno to indicate the error.

ERRORS

If the setenv() function fails, errno is set to one of the following values:

ENOMEM: Sufficient memory is not available to add a variable or its value to the environment.
EINVAL: The envname argument is a null pointer, points to an empty string, or points to a string containing an equal (=) character.

If the unsetenv() function fails, errno is set to the following value:

EINVAL: The envname argument is a null pointer, points to an empty string, or points to a string containing an equal (=) character.

EXAMPLES

The following code adds a new environment variable NEWHOME to the current environment.

setenv("NEWHOME","/tmp/HOME",1); 

The following code updates the variable HOME.

const char *envname="HOME"; 
const char *envval="/tmp/home"; 
setenv(envname,envval,1); 

The following code removes the variable NEWHOME from the current environment.

unsetenv("NEWHOME"); 

WARNINGS

The setenv() and unsetenv() functions manipulate the environment pointed to by environ, and can be used in conjunction with getenv(). However, envp (the third argument to main) is not changed.

The setenv() uses malloc() to enlarge the environment (see malloc(3C)).

After the setenv() or unsetenv() function is called, environment variables may not be in alphabetical order.

AUTHOR

setenv() and unsetenv() were developed by HP.

STANDARDS CONFORMANCE

setenv(): UNIX 03

unsetenv(): UNIX 03