# getenv

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



           getenv — get value of an environment variable
    


## SYNOPSIS



           #include <stdlib.h>
    
           char *getenv(const char *_name_);
    


## DESCRIPTION



           The functionality described on this reference page is aligned with
           the ISO C standard. Any conflict between the requirements
           described here and the ISO C standard is unintentional. This
           volume of POSIX.1‐2017 defers to the ISO C standard.
    
           The _getenv_() function shall search the environment of the calling
           process (see the Base Definitions volume of POSIX.1‐2017, _Chapter_
           _8_ , _Environment Variables_) for the environment variable _name_ if it
           exists and return a pointer to the value of the environment
           variable. If the specified environment variable cannot be found, a
           null pointer shall be returned. The application shall ensure that
           it does not modify the string pointed to by the _getenv_() function.
    
           The returned string pointer might be invalidated or the string
           content might be overwritten by a subsequent call to _getenv_(),
           _setenv_(), _unsetenv_(),
           or (if supported) _putenv_() but they shall not be affected by a
           call to any other function in this volume of POSIX.1‐2017.
    
           The returned string pointer might also be invalidated if the
           calling thread is terminated.
    
           The _getenv_() function need not be thread-safe.
    


## RETURN VALUE



           Upon successful completion, _getenv_() shall return a pointer to a
           string containing the _value_ for the specified _name_.  If the
           specified _name_ cannot be found in the environment of the calling
           process, a null pointer shall be returned.
    


## ERRORS



           No errors are defined.
    
           _The following sections are informative._
    


## EXAMPLES



       **Getting the Value of an Environment Variable**
           The following example gets the value of the _HOME_ environment
           variable.
    
               #include <stdlib.h>
               ...
               const char *name = "HOME";
               char *value;
    
               value = getenv(name);
    


## APPLICATION USAGE



           None.
    


## RATIONALE



           The _clearenv_() function was considered but rejected. The _putenv_()
           function has now been included for alignment with the Single UNIX
           Specification.
    
           The _getenv_() function is inherently not thread-safe because it
           returns a value pointing to static data.
    
           Conforming applications are required not to directly modify the
           pointers to which _environ_ points, but to use only the _setenv_(),
           _unsetenv_(), and _putenv_() functions, or assignment to _environ_
           itself, to manipulate the process environment. This constraint
           allows the implementation to properly manage the memory it
           allocates. This enables the implementation to free any space it
           has allocated to strings (and perhaps the pointers to them) stored
           in _environ_ when _unsetenv_() is called. A C runtime start-up
           procedure (that which invokes _main_() and perhaps initializes
           _environ_) can also initialize a flag indicating that none of the
           environment has yet been copied to allocated storage, or that the
           separate table has not yet been initialized. If the application
           switches to a complete new environment by assigning a new value to
           _environ_ , this can be detected by _getenv_(), _setenv_(), _unsetenv_(),
           or _putenv_() and the implementation can at that point reinitialize
           based on the new environment. (This may include copying the
           environment strings into a new array and assigning _environ_ to
           point to it.)
    
           In fact, for higher performance of _getenv_(), implementations that
           do not provide _putenv_() could also maintain a separate copy of the
           environment in a data structure that could be searched much more
           quickly (such as an indexed hash table, or a binary tree), and
           update both it and the linear list at _environ_ when _setenv_() or
           _unsetenv_() is invoked. On implementations that do provide
           _putenv_(), such a copy might still be worthwhile but would need to
           allow for the fact that applications can directly modify the
           content of environment strings added with _putenv_().  For example,
           if an environment string found by searching the copy is one that
           was added using _putenv_(), the implementation would need to check
           that the string in _environ_ still has the same name (and value, if
           the copy includes values), and whenever searching the copy
           produces no match the implementation would then need to search
           each environment string in _environ_ that was added using _putenv_()
           in case any of them have changed their names and now match. Thus,
           each use of _putenv_() to add to the environment would reduce the
           speed advantage of having the copy.
    
           Performance of _getenv_() can be important for applications which
           have large numbers of environment variables. Typically,
           applications like this use the environment as a resource database
           of user-configurable parameters.  The fact that these variables
           are in the user's shell environment usually means that any other
           program that uses environment variables (such as _ls_ , which
           attempts to use _COLUMNS_), or really almost any utility (_LANG_ ,
           _LC_ALL_ , and so on) is similarly slowed down by the linear search
           through the variables.
    
           An implementation that maintains separate data structures, or even
           one that manages the memory it consumes, is not currently required
           as it was thought it would reduce consensus among implementors who
           do not want to change their historical implementations.
    


## FUTURE DIRECTIONS



           A future version may add one or more functions to access and
           modify the environment in a thread-safe manner.
    


* * *