PUTENV(3P)                                          POSIX Programmer's Manual                                         PUTENV(3P)



PROLOG
       This  manual  page is part of the POSIX Programmer's Manual.  The Linux implementation of this interface may differ (con-
       sult the corresponding Linux manual page for details of Linux behavior), or the  interface  may  not  be  implemented  on
       Linux.

NAME
       putenv - change or add a value to an environment

SYNOPSIS
       #include <stdlib.h>

       int putenv(char *string);


DESCRIPTION
       The  putenv() function shall use the string argument to set environment variable values. The string argument should point
       to a string of the form " name= value ".  The putenv() function shall make the value of  the  environment  variable  name
       equal  to  value  by altering an existing variable or creating a new one. In either case, the string pointed to by string
       shall become part of the environment, so altering the string shall change the environment. The space used by string is no
       longer used once a new string which defines name is passed to putenv().

       The  putenv()  function  need  not  be  reentrant.  A function that is not required to be reentrant is not required to be
       thread-safe.

RETURN VALUE
       Upon successful completion, putenv() shall return 0; otherwise, it shall return a non-zero value and set errno  to  indi-
       cate the error.

ERRORS
       The putenv() function may fail if:

       ENOMEM Insufficient memory was available.


       The following sections are informative.

EXAMPLES
   Changing the Value of an Environment Variable
       The following example changes the value of the HOME environment variable to the value /usr/home.


              #include <stdlib.h>
              ...
              static char *var = "HOME=/usr/home";
              int ret;


              ret = putenv(var);

APPLICATION USAGE
       The putenv() function manipulates the environment pointed to by environ, and can be used in conjunction with getenv().

       See exec(), for restrictions on changing the environment in multi-threaded applications.

       This routine may use malloc() to enlarge the environment.

       A  potential  error is to call putenv() with an automatic variable as the argument, then return from the calling function
       while string is still part of the environment.

       The setenv() function is preferred over this function.

RATIONALE
       The standard developers noted that putenv() is the only function available to add to the environment  without  permitting
       memory leaks.

FUTURE DIRECTIONS
       None.

SEE ALSO
       exec(), getenv(), malloc(), setenv(), the Base Definitions volume of IEEE Std 1003.1-2001, <stdlib.h>

COPYRIGHT
       Portions  of  this  text are reprinted and reproduced in electronic form from IEEE Std 1003.1, 2003 Edition, Standard for
       Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6,  Copy-
       right (C) 2001-2003 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any
       discrepancy between this version and the original IEEE and The Open Group Standard, the original IEEE and The Open  Group
       Standard   is   the   referee   document.   The   original   Standard   can   be   obtained  online  at  http://www.open-
       group.org/unix/online.html .



IEEE/The Open Group                                           2003                                                    PUTENV(3P)