# setenv

## 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.
    


## ERRORS



           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.
    


* * *