'\" et
.TH SETENV "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual"
.\"
.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
\(em add or change environment variable
.SH SYNOPSIS
.LP
.nf
#include <stdlib.h>
.P
int setenv(const char *\fIenvname\fP, const char *\fIenvval\fP, int \fIoverwrite\fP);
.fi
.SH DESCRIPTION
The
\fIsetenv\fR()
function shall update or add a variable in the environment of the
calling process. The
.IR envname
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
.IR envval
points. The function shall fail if
.IR envname
points to a string which contains an
.BR '=' 
character. If the environment variable named by
.IR envname
already exists and the value of
.IR overwrite
is non-zero, the function shall return success and the environment
shall be updated. If the environment variable named by
.IR envname
already exists and the value of
.IR overwrite
is zero, the function shall return success and the environment shall
remain unchanged.
.P
The
\fIsetenv\fR()
function shall update the list of pointers to which
.IR environ
points.
.P
The strings described by
.IR envname
and
.IR envval
are copied by this function.
.P
The
\fIsetenv\fR()
function need not be thread-safe.
.SH "RETURN VALUE"
Upon successful completion, zero shall be returned. Otherwise, \-1
shall be returned,
.IR errno
set to indicate the error, and the environment shall be unchanged.
.SH ERRORS
The
\fIsetenv\fR()
function shall fail if:
.TP
.BR EINVAL
The
.IR envname
argument points to an empty string or points to a string containing an
.BR '=' 
character.
.TP
.BR ENOMEM
Insufficient memory was available to add a variable or its value to the
environment.
.LP
.IR "The following sections are informative."
.SH EXAMPLES
None.
.SH "APPLICATION USAGE"
See
\fIexec\fR()
for restrictions on changing the environment in multi-threaded
applications.
.SH RATIONALE
Unanticipated results may occur if
\fIsetenv\fR()
changes the external variable
.IR environ .
In particular, if the optional
.IR envp
argument to
\fImain\fR()
is present, it is not changed, and thus may point to an obsolete copy
of the environment (as may any other copy of
.IR environ ).
However, other than the aforementioned restriction, the standard
developers intended that the traditional method of walking through
the environment by way of the
.IR environ
pointer must be supported.
.P
It was decided that
\fIsetenv\fR()
should be required by this version because it addresses a piece of
missing functionality, and does not impose a significant burden on the
implementor.
.P
There was considerable debate as to whether the System V
\fIputenv\fR()
function or the BSD
\fIsetenv\fR()
function should be required as a mandatory function. The
\fIsetenv\fR()
function was chosen because it permitted the implementation of the
\fIunsetenv\fR()
function to delete environmental variables, without specifying an
additional interface. The
\fIputenv\fR()
function is available as part of the XSI option.
.P
The standard developers considered requiring that
\fIsetenv\fR()
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
.IR exec ,
which returns an indication of this error condition.
.P
See also the RATIONALE section in
.IR "\fIgetenv\fR\^(\|)".
.SH "FUTURE DIRECTIONS"
None.
.SH "SEE ALSO"
.IR "\fIexec\fR\^",
.IR "\fIgetenv\fR\^(\|)",
.IR "\fIputenv\fR\^(\|)",
.IR "\fIunsetenv\fR\^(\|)"
.P
The Base Definitions volume of POSIX.1\(hy2017,
.IR "\fB<stdlib.h>\fP",
.IR "\fB<sys_types.h>\fP",
.IR "\fB<unistd.h>\fP"
.\"
.SH COPYRIGHT
Portions of this text are reprinted and reproduced in electronic form
from IEEE Std 1003.1-2017, Standard for Information Technology
-- Portable Operating System Interface (POSIX), The Open Group Base
Specifications Issue 7, 2018 Edition,
Copyright (C) 2018 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 .
.PP
Any typographical or formatting errors that appear
in this page are most likely
to have been introduced during the conversion of the source files to
man page format. To report such errors, see
https://www.kernel.org/doc/man-pages/reporting_bugs.html .