Originální popis anglicky:
setenv - add or change environment variable
Návod, kniha: POSIX Programmer's Manual
#include <stdlib.h>
int setenv(const char *
envname, const char
*envval, int
overwrite );
The
setenv() function shall update or add a variable in the environment
of the calling process. The
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
envval points.
The function shall fail if
envname points to a string which contains an
'=' character. If the environment variable named by
envname
already exists and the value of
overwrite is non-zero, the function
shall return success and the environment shall be updated. If the environment
variable named by
envname already exists and the value of
overwrite is zero, the function shall return success and the
environment shall remain unchanged.
If the application modifies
environ or the pointers to which it points,
the behavior of
setenv() is undefined. The
setenv() function
shall update the list of pointers to which
environ points.
The strings described by
envname and
envval are copied by this
function.
The
setenv() function need not be reentrant. A function that is not
required to be reentrant is not required to be thread-safe.
Upon successful completion, zero shall be returned. Otherwise, -1 shall be
returned,
errno set to indicate the error, and the environment shall be
unchanged.
The
setenv() function shall fail if:
- EINVAL
- The name argument is a null pointer, points to an
empty string, or points to a string containing an '='
character.
- ENOMEM
- Insufficient memory was available to add a variable or its
value to the environment.
The following sections are informative.
None.
See
exec() , for restrictions on changing the environment in
multi-threaded applications.
Unanticipated results may occur if
setenv() changes the external variable
environ. In particular, if the optional
envp argument to
main() is present, it is not changed, and thus may point to an obsolete
copy of the environment (as may any other copy of
environ). 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
environ pointer must be
supported.
It was decided that
setenv() should be required by this revision because
it addresses a piece of missing functionality, and does not impose a
significant burden on the implementor.
There was considerable debate as to whether the System V
putenv()
function or the BSD
setenv() function should be required as a mandatory
function. The
setenv() function was chosen because it permitted the
implementation of the
unsetenv() function to delete environmental
variables, without specifying an additional interface. The
putenv()
function is available as an XSI extension.
The standard developers considered requiring that
setenv() 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
exec, which returns an
indication of this error condition.
None.
exec() ,
getenv() ,
unsetenv() , the Base Definitions
volume of IEEE Std 1003.1-2001,
<stdlib.h>,
<sys/types.h>,
<unistd.h>
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
.
