putenv(3C)

NAME

     putenv - change or add value to environment

SYNOPSIS

     #include <stdlib.h>

     int putenv(char *string);

DESCRIPTION

     The putenv() function makes the  value  of  the  environment
     variable  name  equal to value by altering an existing vari-
     able or creating a new  one.  In  either  case,  the  string
     pointed  to  by  string  becomes part of the environment, so
     altering the string will change the environment.

     The  string  argument  points  to  a  string  of  the   form
     name=value.  The space used by string is no longer used once
     a new string-defining name is passed to putenv().

     The  putenv()  function  uses  malloc(3C)  to  enlarge   the
     environment.

     After putenv() is called, environment variables are  not  in
     alphabetical order.

RETURN VALUES

     The putenv() functions returns a non-zero value  if  it  was
     unable  to  obtain  enough  space  using   malloc(3C) for an
     expanded environment. Otherwise, 0 is returned.

ERRORS

     The putenv() function may fail if:

     ENOMEM
           Insufficient memory was available.

USAGE

     The  putenv()  function  can  be  safely  called  from  mul-
     tithreaded  programs.   Caution must be exercised when using
     this function  and  getenv(3C)  in  multithreaded  programs.
     These  functions  examine  and  modify the environment list,
     which is shared by all threads in  a  program.   The  system
     prevents  the list from being accessed simultaneously by two
     different  threads.   It  does  not,  however,  prevent  two
     threads  from  successively  accessing  the environment list
     using putenv() or getenv().

ATTRIBUTES

     See attributes(5) for descriptions of the  following  attri-
     butes:

     ____________________________________________________________
    |       ATTRIBUTE TYPE        |       ATTRIBUTE VALUE       |
    |_____________________________|_____________________________|
    | MT-Level                    | Safe                        |
    |_____________________________|_____________________________|

SEE ALSO

     exec(2), getenv(3C), malloc(3C), attributes(5), environ(5)

WARNINGS

     The string argument should not be an automatic variable.  It
     should  be  declared static if it is declared within a func-
     tion because it cannot be automatically declared.  A  poten-
     tial  error  is  to  call  putenv()  with  a  pointer  to an
     automatic variable as the argument and to then exit the cal-
     ling function while string is still part of the environment.