Creates new environment variables; modifies or removes existing ones.
| #include <stdlib.h> | Required only for function declarations |
int _putenv( char *envstring );
| envstring | Environment-string definition |
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).
The envstring argument must be a pointer to a string with 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. A variable can be removed from the environment by specifying an empty string—that is, by specifying only varname=.
This function affects only the environment that is local to the currently running process; it cannot be used to modify the command-level environment. When the currently running process terminates, the environment reverts to the level of the parent process (in most cases, the operating system level). However, the environment affected by _putenv can be passed to any child processes created by _spawn, _exec, or system, and these child processes get any new items added by _putenv.
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 a pointer to a local variable, then exit the function in which the variable is declared.
The _putenv function operates only on data structures accessible to the run-time library and not on the environment “segment” created for a process by the operating system.
Note that environment-table entries must not be changed directly. If an entry must be changed, use _putenv. To modify the returned value without affecting the environment table, use _strdup or strcpy to make a copy of the string.
The getenv and _putenv functions use the global variable environ to access the environment table. The _putenv function may change the value of environ, thus invalidating the envp argument to the main function. Therefore, it is safer to use the environ variable to access the environment information.
The _putenv function returns 0 if it is successful. A return value of –1 indicates an error.
Standards:UNIX
16-Bit:DOS, QWIN, WIN, WIN DLL
32-Bit:DOS32X
Use _putenv for compatibility with ANSI naming conventions of non-ANSI functions. Use putenv and link with OLDNAMES.LIB for UNIX compatibility.
/* 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 );
}
Original LIB variable is: C:\LIB
New LIB variable is: c:\mylib;c:\yourlib