Click above to get retro games delivered to your door ever month!

Synopsis:
    #include <process.h>
    int putenv( const char *env_name );
    int _putenv( const char *env_name );
    int _wputenv( const wchar_t *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 DOS set command or with the putenv function.
     All entries in the environment list can be displayed by using the DOS
    set command 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 is added to the environment list.
     When the value of env_name has the format


             env_name=

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

    The matching is case-insensitive; all lowercase letters are treated as
    if they were in upper case.

    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.

    The _putenv function is identical to putenv.  Use _putenv for ANSI
    naming conventions.

    The _wputenv function is a wide-character version of putenv the env_name
    argument to _wputenv is a wide-character string.

    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.
     .  If the argument env_name is not a literal string, you should
        duplicate the string, since putenv does not copy the value; for
        example,


                 putenv( _strdup( buffer ) );
     .  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.

    To assign a string to a variable and place it in the environment list:


             C>SET INCLUDE=C:\WATCOM\H

    To see what variables are in the environment list, and their current
    assignments:


             C>SET
             COMSPEC=C:\COMMAND.COM
             PATH=C:\;C:\WATCOM
             INCLUDE=C:\WATCOM\H

             C>


Returns:
    The putenv function returns zero when it is successfully executed and
    returns -1 when it fails.

Errors:
    When an error has occurred,  errno contains a value indicating the type
    of error that has been detected.

    ENOMEM
        Not enough memory to allocate a new environment string.


Example:
    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=mylib;yourlib" ) != 0 )
            printf( "putenv failed" );
        path = getenv( "INCLUDE" );
        if( path != NULL )
            printf( "INCLUDE=%s\n", path );
        if( putenv( "INCLUDE=" ) != 0 )
            printf( "putenv failed" );
      }

    produces the following:

    INCLUDE=C:\WATCOM\H
    INCLUDE=mylib;yourlib

Classification:
    WATCOM

Systems:
     putenv - All

    _putenv - DOS, Windows, Win386, Win32, QNX/16, OS/2 1.x(all), OS/2-32
    _wputenv - DOS, Windows, Win386, Win32, QNX/16, OS/2 1.x(all), OS/2-32

See Also:
    clearenv, getenv, setenv