setenv()

Create or change an environment variable

Synopsis:

#include <stdlib.h>

int setenv( const char* name,
            const char* value,
            int overwrite );

Arguments:

name

The name of the environment variable that you want to set.

value

NULL, or the value for the environment variable; see below.

overwrite

A nonzero value if you want the function to overwrite the variable if it exists, or 0 if you don't want to overwrite the variable.

Library:

libc

Use the -l c option to qcc to link against this library. This library is usually included automatically.

Description:

The setenv() function sets the environment variable name to value. If name doesn't exist in the environment, it's created; if name exists and overwrite is nonzero, the variable's old value is overwritten with value; otherwise, it isn't changed.

---

This function doesn't free any memory. If you want to change the value of an existing environment variable, you should use putenv() instead.

---

Copies of the specified name and value are placed in the environment.

If value is NULL, the environment variable specified by name is removed from the environment.

---

The value of the global environ pointer could be changed by a call to the setenv() function.

---

Environment variable names are case-sensitive.

Returns:

0

Success.

Nonzero

An error occurred (errno is set).

Errors:

ENOMEM

Not enough memory to allocate a new environment variable.

Examples:

Change the string assigned to INCLUDE and then display the new string:

#include <stdio.h>
#include <stdlib.h>

int main( void )
{
    char* path;

    if( setenv( "INCLUDE",
                "/usr/nto/include:/home/fred/include", 
                1 ) == 0 ) {
        if( (path = getenv( "INCLUDE" )) != NULL ) {
            printf( "INCLUDE=%s\n", path );
        }
    }

    return EXIT_SUCCESS;
}

Classification:

POSIX 1003.1

Caveats:

The setenv() function manipulates the environment pointed to by the global environ variable.

See also:

clearenv(), errno, execl(), execle(), execlp(), execlpe(), execv(), execve(), execvp(), execvpe(), getenv(), putenv(), searchenv(), spawn(), spawnl(), spawnle(), spawnlp(), spawnlpe(), spawnp(), spawnv(), spawnve(), spawnvp(), spawnvpe(), system(), unsetenv()