добавить или изменить переменную среды (add or change environment variable)
Пролог (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.
Имя (Name)
setenv — add or change environment variable
Синопсис (Synopsis)
#include <stdlib.h>
int setenv(const char *envname, const char *envval, int overwrite);
Описание (Description)
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.
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 thread-safe.
Возвращаемое значение (Return value)
Upon successful completion, zero shall be returned. Otherwise, -1
shall be returned, errno set to indicate the error, and the
environment shall be unchanged.
Ошибки (Error)
The setenv() function shall fail if:
EINVAL The envname argument 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.
Примеры (Examples)
None.
Использование в приложениях (Application usage)
See exec() for restrictions on changing the environment in multi-
threaded applications.
Обоснование (Rationale)
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 standard developers 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 version
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 part of the XSI
option.
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.
See also the RATIONALE section in getenv(3p).
Будущие направления (Future directions)
None.
Смотри также (See also)
exec(1p), getenv(3p), putenv(3p), unsetenv(3p)
The Base Definitions volume of POSIX.1‐2017, stdlib.h(0p),
sys_types.h(0p), unistd.h(0p)
