Important Notice

The pages on this site contain documentation for very old MS-DOS software, purely for historical purposes. If you're looking for up-to-date documentation, particularly for programming, you should not rely on the information found here, as it will be woefully out of date.

 ◄Summary► ◄Example►                         ◄Up► ◄Contents► ◄Index► ◄Back►
────────────────────────────────────────────────────────────────────────────
 
     The putenv function adds new environment variables or modifies the
     values of existing environment variables. These 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, it is replaced by
     <string>; otherwise, the new string is added to the environment. A
     variable can be set to an empty value by specifying an empty
     string.
 
     This function affects only the environment that is local to the
     currently running process; it cannot be used to enter new items in
     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 or exec, and these child processes get
     any new items added by putenv.
 
     Never free a pointer to an environment entry, because the
     environment variable will point into freed space. A similar
     problem can occur if you pass a pointer to a local variable to
     putenv, then exit the function in which the variable is declared.
 
     The putenv function operates only on the run-time library's
     accessible data structures, not on the environment segment
     created for a process by DOS or OS/2.
 
     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.
 
     Return Value
 
     The putenv function returns 0 if it is successful. A return value
     of -1 indicates an error.
                                    -♦-