putenv

add, change or delete an environment variable

Synopsis:

#include <process.h>
int putenv( const char *env_name );

Description:

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

• Entries can be added to the environment list with the export shell command, env utility, putenv(), or setenv().
• All entries in the environment list can be displayed by using the export shell command or env utility with no arguments.
• A program can obtain the value for an environment variable by using the getenv() function.

When the value of env_name has the format

env_name=value an environment name and its value are added to the environment list.

When the value of env_name has the format

env_name=

the environment name and value are removed from the environment list.

The space into which environment names and their values are placed is limited. Consequently, the putenv() function can fail when there is insufficient space remaining to store an additional value.

    putenv( strdup( buffer ) );

To use the export command to assign a string to a variable and place it in the environment list, type something like the following:

    export INCLUDE=/usr/include

Type the export command without any arguments to see what variables are in the environment list, and their current assignments. An example of the output is as follows:

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

Returns:

0

Success

(-1)

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

Errors:

ENOMEM

There was not enough memory to allocate a new environment string.

See also:

clearenv(), errno, getenv(), setenv()

Examples:

The following gets the string currently assigned to INCLUDE and displays it, assigns a new value to it, gets and displays it, and then removes the environment name and value.

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

void main()
  {
    char *path;
    path = getenv( "INCLUDE" );
    if( path != NULL )
      printf( "INCLUDE=%s\n", path );
    if( putenv( "INCLUDE=//5/usr/include" ) != 0 )
      printf( "putenv failed" );
    path = getenv( "INCLUDE" );
    if( path != NULL )
      printf( "INCLUDE=%s\n", path );
    if( putenv( "INCLUDE=" ) != 0 )
      printf( "putenv failed" );
  }

This program produces the following output:

INCLUDE=/usr/include
INCLUDE=//5/usr/include

Classification:

WATCOM

Systems:

All (except Netware, DOS/PM)