setenv()

set one or more environment variables

Synopsis:

#include <env.h>

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

Description:

The environment consists of a list of environment variables, each of which has a value associated with it.

• You can add entries to the environment with the export shell command, the env utility, or the putenv() or setenv() functions.
• You can display all the entries in the environment by using the export or env shell command with no arguments.
• A program can obtain the value of an environment variable by using the getenv() function.

The setenv() function searches the environment for an entry of the form name=value. If no such string is present, setenv() adds an entry of the form name=newvalue to the environment. Otherwise, if the overwrite argument is nonzero, setenv() changes the existing value to newvalue.

If the newvalue pointer is NULL, all strings of the form name=value in the environment list will be deleted.

The value of the global pointer environ may change across a call to the setenv() function.

The setenv() function makes copies of the strings associated with name and newvalue before manipulating the environment.

The matching is case-sensitive; lowercase letters are treated as different from uppercase letters.

To assign a string to a variable and place it in the environment list, use the export command, as follows:

     export INCLUDE=/usr/include

To see what variables are in the environment list, and their current assignments, type the export command without any arguments. The output will be like the following:

    SHELL=ksh
    TERM=qnx
    LOGNAME=fred
    PATH=:/bin:/usr/bin
    HOME=/home/fred
    INCLUDE=/usr/include
    LIB=/usr/lib

Returns:

0

Success

Nonzero

An error occurred. errno is set to indicate the error.

Errors:

ENOMEM

Not enough memory to allocate a new environment string.

Examples:

The following changes the string assigned to INCLUDE and then displays the new string.

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

int main( void )
  {
    char *path;

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

Classification:

WATCOM

See also:

clearenv(), errno, exec... functions, getenv(), putenv(), _searchenv(), searchenv(), spawn... functions, system()