GNU Info

(libc.info)Environment Access

---

Next: Standard Environment Up: Environment Variables

---

Enter node , (file) or (file)node

Environment Access
------------------

   The value of an environment variable can be accessed with the
`getenv' function.  This is declared in the header file `stdlib.h'.
All of the following functions can be safely used in multi-threaded
programs.  It is made sure that concurrent modifications to the
environment do not lead to errors.

 - Function: char * getenv (const char *NAME)
     This function returns a string that is the value of the environment
     variable NAME.  You must not modify this string.  In some non-Unix
     systems not using the GNU library, it might be overwritten by
     subsequent calls to `getenv' (but not by any other library
     function).  If the environment variable NAME is not defined, the
     value is a null pointer.

 - Function: int putenv (char *STRING)
     The `putenv' function adds or removes definitions from the
     environment.  If the STRING is of the form `NAME=VALUE', the
     definition is added to the environment.  Otherwise, the STRING is
     interpreted as the name of an environment variable, and any
     definition for this variable in the environment is removed.

     The difference to the `setenv' function is that the exact string
     given as the parameter STRING is put into the environment.  If the
     user should change the string after the `putenv' call this will
     reflect in automatically in the environment.  This also requires
     that STRING is no automatic variable which scope is left before the
     variable is removed from the environment.  The same applies of
     course to dynamically allocated variables which are freed later.

     This function is part of the extended Unix interface.  Since it
     was also available in old SVID libraries you should define either
     _XOPEN_SOURCE or _SVID_SOURCE before including any header.

 - Function: int setenv (const char *NAME, const char *VALUE, int
          REPLACE)
     The `setenv' function can be used to add a new definition to the
     environment.  The entry with the name NAME is replaced by the
     value `NAME=VALUE'.  Please note that this is also true if VALUE
     is the empty string.  To do this a new string is created and the
     strings NAME and VALUE are copied.  A null pointer for the VALUE
     parameter is illegal.  If the environment already contains an
     entry with key NAME the REPLACE parameter controls the action.  If
     replace is zero, nothing happens.  Otherwise the old entry is
     replaced by the new one.

     Please note that you cannot remove an entry completely using this
     function.

     This function was originally part of the BSD library but is now
     part of the Unix standard.

 - Function: int unsetenv (const char *NAME)
     Using this function one can remove an entry completely from the
     environment.  If the environment contains an entry with the key
     NAME this whole entry is removed.  A call to this function is
     equivalent to a call to `putenv' when the VALUE part of the string
     is empty.

     The function return `-1' if NAME is a null pointer, points to an
     empty string, or points to a string containing a `=' character.
     It returns `0' if the call succeeded.

     This function was originally part of the BSD library but is now
     part of the Unix standard.  The BSD version had no return value,
     though.

   There is one more function to modify the whole environment.  This
function is said to be used in the POSIX.9 (POSIX bindings for Fortran
77) and so one should expect it did made it into POSIX.1.  But this
never happened.  But we still provide this function as a GNU extension
to enable writing standard compliant Fortran environments.

 - Function: int clearenv (void)
     The `clearenv' function removes all entries from the environment.
     Using `putenv' and `setenv' new entries can be added again later.

     If the function is successful it returns `0'.  Otherwise the return
     value is nonzero.

   You can deal directly with the underlying representation of
environment objects to add more variables to the environment (for
example, to communicate with another program you are about to execute;
Note: Executing a File).

 - Variable: char ** environ
     The environment is represented as an array of strings.  Each
     string is of the format `NAME=VALUE'.  The order in which strings
     appear in the environment is not significant, but the same NAME
     must not appear more than once.  The last element of the array is
     a null pointer.

     This variable is declared in the header file `unistd.h'.

     If you just want to get the value of an environment variable, use
     `getenv'.

   Unix systems, and the GNU system, pass the initial value of
`environ' as the third argument to `main'.  Note: Program Arguments.