[ Previous | Next | Table of Contents | Index | Library Home | Legal | Search ]

Technical Reference: Base Operating System and Extensions, Volume 1

putenv Subroutine


Sets an environment variable.


Standard C Library (libc.a)


int putenv ( String)
char *String;


Attention: Unpredictable results can occur if a subroutine passes the putenv subroutine a pointer to an automatic variable and then returns while the variable is still part of the environment.

The putenv subroutine sets the value of an environment variable by altering an existing variable or by creating a new one. The String parameter points to a string of the form Name=Value, where Name is the environment variable and Value is the new value for it.

The memory space pointed to by the String parameter becomes part of the environment, so that altering the string effectively changes part of the environment. The space is no longer used after the value of the environment variable is changed by calling the putenv subroutine again. Also, after the putenv subroutine is called, environment variables are not necessarily in alphabetical order.

The putenv subroutine manipulates the environ external variable and can be used in conjunction with the getenv subroutine. However, the EnvironmentPointer parameter, the third parameter to the main subroutine, is not changed.

The putenv subroutine uses the malloc subroutine to enlarge the environment.


String A pointer to the Name=Value string.

Return Values

Upon successful completion, a value of 0 is returned. If the malloc subroutine is unable to obtain sufficient space to expand the environment, then the putenv subroutine returns a nonzero value.

Implementation Specifics

This subroutine is part of Base Operating System (BOS) Runtime.

Related Information

The exec: execl, execv, execle, execlp, execvp, or exect (exec: execl, execle, execlp, execv, execve, execvp, or exect Subroutine) subroutine, getenv (getenv Subroutine) subroutine, malloc (malloc, free, realloc, calloc, mallopt, mallinfo, alloca, or valloc Subroutine) subroutine.

[ Previous | Next | Table of Contents | Index | Library Home | Legal | Search ]