.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved 
.TH "SETENV" 3P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual"
.\" setenv 
.SH PROLOG
This manual page is part of the POSIX Programmer's Manual.
The Linux implementation of this interface may differ (consult
the corresponding Linux manual page for details of Linux behavior),
or the interface may not be implemented on Linux.
.SH NAME
setenv \- add or change environment variable
.SH SYNOPSIS
.LP
\fB#include <stdlib.h>
.br
.sp
int setenv(const char *\fP\fIenvname\fP\fB, const char *\fP\fIenvval\fP\fB,
int\fP \fIoverwrite\fP\fB); \fP
\fB
.br
\fP
.SH DESCRIPTION
.LP
The \fIsetenv\fP() function shall update or add a variable in the
environment of the calling process. The \fIenvname\fP
argument points to a string containing the name of an environment
variable to be added or altered. The environment variable shall
be set to the value to which \fIenvval\fP points. The function shall
fail if \fIenvname\fP points to a string which contains an
\fB'='\fP character. If the environment variable named by \fIenvname\fP
already exists and the value of \fIoverwrite\fP is
non-zero, the function shall return success and the environment shall
be updated. If the environment variable named by
\fIenvname\fP already exists and the value of \fIoverwrite\fP is zero,
the function shall return success and the environment
shall remain unchanged.
.LP
If the application modifies \fIenviron\fP or the pointers to which
it points, the behavior of \fIsetenv\fP() is undefined. The
\fIsetenv\fP() function shall update the list of pointers to which
\fIenviron\fP points.
.LP
The strings described by \fIenvname\fP and \fIenvval\fP are copied
by this function.
.LP
The \fIsetenv\fP() function need not be reentrant. A function that
is not required to be reentrant is not required to be
thread-safe.
.SH RETURN VALUE
.LP
Upon successful completion, zero shall be returned. Otherwise, -1
shall be returned, \fIerrno\fP set to indicate the error, and
the environment shall be unchanged.
.SH ERRORS
.LP
The \fIsetenv\fP() function shall fail if:
.TP 7
.B EINVAL
The \fIname\fP argument is a null pointer, points to an empty string,
or points to a string containing an \fB'='\fP
character.
.TP 7
.B ENOMEM
Insufficient memory was available to add a variable or its value to
the environment.
.sp
.LP
\fIThe following sections are informative.\fP
.SH EXAMPLES
.LP
None.
.SH APPLICATION USAGE
.LP
See \fIexec\fP(), for restrictions on changing the environment in
multi-threaded applications.
.SH RATIONALE
.LP
Unanticipated results may occur if \fIsetenv\fP() changes the external
variable \fIenviron\fP. In particular, if the optional
\fIenvp\fP argument to \fImain\fP() is present, it is not changed,
and thus may point to an obsolete copy of the environment (as
may any other copy of \fIenviron\fP). However, other than the aforementioned
restriction, the developers of
IEEE\ Std\ 1003.1-2001 intended that the traditional method of walking
through the environment by way of the \fIenviron\fP
pointer must be supported.
.LP
It was decided that \fIsetenv\fP() should be required by this revision
because it addresses a piece of missing functionality,
and does not impose a significant burden on the implementor.
.LP
There was considerable debate as to whether the System V \fIputenv\fP()
function or the
BSD \fIsetenv\fP() function should be required as a mandatory function.
The \fIsetenv\fP() function was chosen because it
permitted the implementation of the \fIunsetenv\fP() function to delete
environmental
variables, without specifying an additional interface. The \fIputenv\fP()
function is
available as an XSI extension.
.LP
The standard developers considered requiring that \fIsetenv\fP() indicate
an error when a call to it would result in exceeding
{ARG_MAX}. The requirement was rejected since the condition might
be temporary, with the application eventually reducing the
environment size. The ultimate success or failure depends on the size
at the time of a call to \fIexec\fP, which returns an indication of
this error condition.
.SH FUTURE DIRECTIONS
.LP
None.
.SH SEE ALSO
.LP
\fIexec\fP(), \fIgetenv\fP(), \fIunsetenv\fP(), the Base Definitions
volume of IEEE\ Std\ 1003.1-2001, \fI<stdlib.h>\fP, \fI<sys/types.h>\fP,
\fI<unistd.h>\fP
.SH 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, Copyright (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.opengroup.org/unix/online.html .