.TH putenv() "" "" "General Function (libc)"
.PC "Add a string to the environment"
.B "#include <stdlib.h>"
\fBint putenv (\fIenvstring\fB)\fR
\fBchar *\fIenvstring\^\fB;\fR
.PP
The function
.B putenv()
puts
.I envstring
into the user's environment.
You can use this function to set a new environmental variable, or to
change the definition of an existing variable.
.PP
.I envstring
must point to a string of the form \fIVARIABLE\^\fB=\fIvalue\fR, where
.I VARIABLE
is the environmental variable being set, and
.I value
is the value to which it is being set.
.PP
.B putenv()
returns zero if all goes well.
If something goes wrong, it returns a value other than zero.
.SH "See Also"
.Xr "environ," environ
.Xr "environmental variables," environva
.Xr "getenv()," getenv
.Xr "libc," libc
.Xr "stdlib.h" stdlib.h
.SH Notes
The global variable
.BR environ ,
which points to a process's environment,
points to an array of pointers to strings rather than to an array of strings.
When
.B putenv()
inserts
.I envstring
into the environment,
it calls
.B malloc()
to enlarge the array of string pointers to which
.B environ
points, then inserts a pointer to
.I envstring
into that array.
It does not copy
.I envstring
anywhere.
.PP
If a process uses
.B putenv()
to insert a string pointer into the environment, it can also call
.B getenv()
to read back that string;
however, the array of strings passed to the process via
.B envp
(the third argument to the function
.BR main() )
is not affected by a call to
.BR putenv() .
For details on
.B environ
and
.BR envp ,
see their entries in the Lexicon.
.PP
It is an error to call
.B putenv()
with a pointer to an automatic variable as the argument, and
then exit the calling function while
.I envstring
is still part of the environment.
For safety's sake,
.I envstring
should point to a string that is static or global.
See the Lexicon entry for
.BR static ,
or see the \*(AS \(sc3.5.1.
