putenv -- Modify Environment Variables

Format

#include <stdlib.h>
int putenv(char *envstring);

Language Level: XPG4, Extension
putenv adds new environment variables or modifies the values of existing environment variables. Environment variables define the environment in which a process runs (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 value of the variable. See the Notes below.

If varname is already part of the environment, string replaces its current value; if not, the new varname is added to the environment with the value string. To set a variable to an empty value, specify an empty string. A variable can be removed from the environment by specifying varname only, for example:

putenv("PATH");

Do not free the envstring pointer while the entry it points to is in use, or the environment variable will point into freed space. A similar problem can occur if you pass a pointer to a local variable to putenv and then exit from the function in which the variable is declared. Once you have added the envstring with putenv, any change to the entry it points to changes the environment used by your program.

The environment manipulated by putenv is local to the process currently running, that is, changes are local to the run-time environment to which the call to putenv is made.

For example, in OS/2 and Windows, if you have an exe and a dll both linking statically to the run-time library, if you call putenv in the exe, the changes will not be reflected in the dll.

You cannot enter new items in your command-level environment using putenv. When the program ends, the environment reverts to the parent process environment. This environment is passed on to some child processes created by the _spawn, exec, or system functions, and they get any new environment variables added using putenv.

On OS/2, DosScanEnv will not reflect any changes made using putenv, but getenv will reflect the changes.

On Windows, GetEnvironmentVariable will not reflect any changes made using putenv, but getenv will reflect the changes.

Notes:

  1. putenv can change the value of _environ, thus invalidating the envp argument to the main function.
  2. You cannot use %envvar%, where envvar is any OS/2 or Windows environment variable, with putenv to concatenate new envstring and old envstring.
  3. In earlier releases of the C/C++ run-time library, putenv began with an underscore (_putenv). Because it is defined by the X/Open standard, the underscore has been removed. For compatibility, IBM C and C++ Compilers will map _putenv to putenv for you.

Return Value
putenv returns 0 if it is successful. A return value of -1 indicates an error.

Example
This example tries to change the environment variable PATH, and then uses getenv to get the current path. If the call to putenv fails, the example writes an error message.

#include <stdlib.h>
#include <stdio.h>
int main(void)
{
   char *pathvar;
   if (-1 == putenv("PATH=a:\\bin;b:\\andy")) {
      printf("putenv failed - out of memory\n");
      return EXIT_FAILURE;
   }
   /* getting and printing the current environment path */
   pathvar = getenv("PATH");
   printf("The current path is: %s\n", pathvar);
   return 0;
   /*****************************************************
      The output should be:
      The current path is: a:\bin;b:\andy
   *****************************************************/
}


Receive Data as Arguments of main


execl - _execvpe -- Load and Run Child Process
getenv -- Search for Environment Variables
_spawnl - _spawnvpe -- Start and Run Child Processes
system -- Invoke the Command Processor
<stdlib.h>