putenv

PUTENV(3)		  Linux Programmer’s Manual		    PUTENV(3)



NAME
       putenv - change or add an environment variable

SYNOPSIS
       #include <stdlib.h>

       int putenv(char *string);

DESCRIPTION
       The  putenv()  function adds or changes the value of environment vari-
       ables.  The argument string is of the form name=value.  If  name	 does
       not  already  exist  in	the  environment, then string is added to the
       environment.  If name does exist, then the value of name in the	envi-
       ronment	is changed to value.  The string pointed to by string becomes
       part of the environment, so altering the string changes	the  environ-
       ment.

RETURN VALUE
       The  putenv()  function	returns	 zero  on  success, or -1 if an error
       occurs.

ERRORS
       ENOMEM Insufficient space to allocate new environment.

NOTES
       The putenv() function is not required to be reentrant, and the one  in
       libc4, libc5 and glibc2.0 is not, but the glibc2.1 version is.

       Description  for libc4, libc5, glibc: If the argument string is of the
       form name, and does not contain an ‘=’ character,  then	the  variable
       name  is	 removed from the environment.	If putenv() has to allocate a
       new array environ, and  the  previous  array  was  also	allocated  by
       putenv(), then it will be freed. In no case will the old storage asso-
       ciated to the environment variable itself be freed.

       The libc4 and libc5 and glibc 2.1.2 versions  conform  to  SUSv2:  the
       pointer	string given to putenv() is used.  In particular, this string
       becomes part of the environment; changing it  later  will  change  the
       environment.   (Thus, it is an error is to call putenv() with an auto-
       matic variable as the argument, then return from the calling  function
       while  string  is  still	 part  of  the	environment.)  However, glibc
       2.0-2.1.1 differs: a copy of the string is used.	 On the one hand this
       causes  a  memory  leak, and on the other hand it violates SUSv2. This
       has been fixed in glibc2.1.2.

       The BSD4.4 version, like glibc 2.0, uses a copy.

       SUSv2 removes the ‘const’ from the prototype, and so does glibc 2.1.3.

CONFORMING TO
       SVID 3, POSIX, BSD 4.3

SEE ALSO
       getenv(3), setenv(3), clearenv(3), unsetenv(3), environ(5)



GNU				  1993-04-08			    PUTENV(3)