Movatterモバイル変換

setenv(3p) — Linux manual page

SETENV(3P)              POSIX Programmer's ManualSETENV(3P)

PROLOG        top

       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        top

       setenv — add or change environment variable

SYNOPSIS        top

       #include <stdlib.h>       int setenv(const char *envname, const char *envval, intoverwrite);

DESCRIPTION        top

       Thesetenv() function shall update or add a variable in the       environment of the calling process. Theenvname 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 whichenvval points. The function shall fail ifenvname       points to a string which contains an'='character. If the       environment variable named byenvname already exists and the value       ofoverwrite is non-zero, the function shall return success and       the environment shall be updated. If the environment variable       named byenvname already exists and the value ofoverwrite is       zero, the function shall return success and the environment shall       remain unchanged.       Thesetenv() function shall update the list of pointers to whichenviron points.       The strings described byenvname andenvval are copied by this       function.       Thesetenv() function need not be thread-safe.

RETURN VALUE        top

       Upon successful completion, zero shall be returned. Otherwise, -1       shall be returned,errno set to indicate the error, and the       environment shall be unchanged.

ERRORS        top

       Thesetenv() function shall fail if:EINVALTheenvname argument points to an empty string or points to              a string containing an'='character.ENOMEMInsufficient memory was available to add a variable or its              value to the environment.The following sections are informative.

EXAMPLES        top

       None.

APPLICATION USAGE        top

       Seeexec() for restrictions on changing the environment in multi-       threaded applications.

RATIONALE        top

       Unanticipated results may occur ifsetenv() changes the external       variableenviron.  In particular, if the optionalenvp argument tomain() is present, it is not changed, and thus may point to an       obsolete copy of the environment (as may any other copy ofenviron).  However, other than the aforementioned restriction, the       standard developers intended that the traditional method of       walking through the environment by way of theenviron pointer must       be supported.       It was decided thatsetenv() 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 Vputenv()       function or the BSDsetenv() function should be required as a       mandatory function. Thesetenv() function was chosen because it       permitted the implementation of theunsetenv() function to delete       environmental variables, without specifying an additional       interface. Theputenv() function is available as part of the XSI       option.       The standard developers considered requiring thatsetenv()       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 toexec, which returns an indication of       this error condition.       See also the RATIONALE section ingetenv(3p).

FUTURE DIRECTIONS        top

       None.

SEE ALSO        top

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)

COPYRIGHT        top

       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 athttp://www.opengroup.org/unix/online.html .       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, seehttps://www.kernel.org/doc/man-pages/reporting_bugs.html .IEEE/The Open Group                2017SETENV(3P)

Pages that refer to this page:stdlib.h(0p), getenv(3p), putenv(3p), unsetenv(3p)

HTML rendering created 2025-09-06 byMichael Kerrisk, author ofThe Linux Programming Interface. For details of in-depthLinux/UNIX system programming training courses that I teach, lookhere. Hosting byjambit GmbH.