_putenv, _wputenv

Creates new environment variables; modifies or removes existing ones.

int_putenv(constchar*envstring);

int_wputenv(constwchar_t*envstring);

Routine	Required Header	Compatibility
_putenv	<stdlib.h>	Win 95, Win NT
_wputenv	<stdlib.h> or <wchar.h>	Win NT

For additional compatibility information, see Compatibility in the Introduction.

Libraries

LIBC.LIB	Single thread static library, retail version
LIBCMT.LIB	Multithread static library, retail version
MSVCRT.LIB	Import library for MSVCRT.DLL, retail version

Return Value

_putenv and _wputenv return 0 if successful, or –1 in the case of an error.

Parameter

envstring

Environment-string definition

Remarks

The _putenv function adds new environment variables or modifies the values of existing environment variables. Environment variables define the environment in which a process executes (for example, the default search path for libraries to be linked with a program). _wputenv is a wide-character version of _putenv; the envstring argument to _wputenv is a wide-character string.

Generic-Text Routine Mappings

TCHAR.H Routine	_UNICODE & _MBCS Not Defined	_MBCS Defined	_UNICODE Defined
_tputenv	_putenv	_putenv	_wputenv

The envstring argument must be a pointer to a string of the form varname=string, where varname is the name of the environment variable to be added or modified and string is the variable’s value. If varname is already part of the environment, its value is replaced by string; otherwise, the new varname variable and its string value are added to the environment. You can remove a variable from the environment by specifying an empty string — in other words, by specifying only varname=.

_putenv and _wputenv affect only the environment that is local to the current process; you cannot use them to modify the command-level environment. That is, these functions operate only on data structures accessible to the run-time library and not on the environment “segment” created for a process by the operating system. When the current process terminates, the environment reverts to the level of the calling process (in most cases, the operating-system level). However, the modified environment can be passed to any new processes created by _spawn, _exec, or system, and these new processes get any new items added by _putenv and _wputenv.

With regard to environment entries, observe the following cautions:

• Do not change an environment entry directly; instead, use _putenv or _wputenv to change it. To modify the return value of _putenv or _wputenv without affecting the environment table, use _strdup or strcpy to make a copy of the string.

• Never free a pointer to an environment entry, because the environment variable will then point to freed space. A similar problem can occur if you pass _putenv or _wputenv a pointer to a local variable, then exit the function in which the variable is declared.

getenv and _putenv use the global variable _environ to access the environment table; _wgetenv and _wputenv use _wenviron. _putenv and _wputenv may change the value of _environ and _wenviron, thus invalidating the envp argument to main and the*_wenvp* argument to wmain. Therefore, it is safer to use _environ or _wenviron to access the environment information. For more information about the relation of _putenv and _wputenv to global variables, see _environ, _wenviron.

Example

/* GETENV.C: This program uses getenv to retrieve
 * the LIB environment variable and then uses
 * _putenv to change it to a new value.
 */

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

void main( void )
{
   char *libvar;

   /* Get the value of the LIB environment variable. */
   libvar = getenv( "LIB" );

   if( libvar != NULL )
      printf( "Original LIB variable is: %s\n", libvar );

   /* Attempt to change path. Note that this only affects the environment
    * variable of the current process. The command processor's environment
    * is not changed.
    */
   _putenv( "LIB=c:\\mylib;c:\\yourlib" );

   /* Get new value. */
   libvar = getenv( "LIB" );

   if( libvar != NULL )
      printf( "New LIB variable is: %s\n", libvar );
}

Output

Original LIB variable is: C:\progra~1\devstu~1\vc\lib
New LIB variable is: c:\mylib;c:\yourlib

Process and Environment Control Routines

See Also   getenv, _searchenv