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.

CAUTION:

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.

Note: 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

Safety:
Cancellation point	No
Interrupt handler	No
Signal handler	No
Thread	Yes

Caveats:

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