Section: POSIX Programmer's Manual (3P)
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.
--- add or change environment variable
int setenv(const char *envname, const char *envval, int overwrite);
function shall update or add a variable in the environment of the
calling process. The
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
points. The function shall fail if
points to a string which contains an
character. If the environment variable named by
already exists and the value of
is non-zero, the function shall return success and the environment
shall be updated. If the environment variable named by
already exists and the value of
is zero, the function shall return success and the environment shall
function shall update the list of pointers to which
The strings described by
are copied by this function.
function need not be thread-safe.
Upon successful completion, zero shall be returned. Otherwise, -1
shall be returned,
set to indicate the error, and the environment shall be unchanged.
function shall fail if:
argument points to an empty string or points to a string containing an
Insufficient memory was available to add a variable or its value to the
The following sections are informative.
for restrictions on changing the environment in multi-threaded
Unanticipated results may occur if
changes the external variable
In particular, if the optional
is present, it is not changed, and thus may point to an obsolete copy
of the environment (as may any other copy of
However, other than the aforementioned restriction, the standard
developers intended that the traditional method of walking through
the environment by way of the
pointer must be supported.
It was decided that
should be required by this version because it addresses a piece of
missing functionality, and does not impose a significant burden on the
There was considerable debate as to whether the System V
function or the BSD
function should be required as a mandatory function. The
function was chosen because it permitted the implementation of the
function to delete environmental variables, without specifying an
additional interface. The
function is available as part of the XSI option.
The standard developers considered requiring that
indicate an error when a call to it would result in exceeding
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
which returns an indication of this error condition.
See also the RATIONALE section in
The Base Definitions volume of POSIX.1-2017,
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
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