getenv, getenv_s

Defined in header `<stdlib.h>`
char getenv( const char name );	(1)
errno_t getenv_s( size_t restrict len, char restrict value, rsize_t valuesz, const char *restrict name );	(2)	(since C11)

1) Searches for an environmental variable with name name in the host-specified environment list and returns a pointer to the string that is associated with the matched environment variable. The set of environmental variables and methods of altering it are implementation-defined.

This function is not required to be thread-safe. Another call to getenv, as well as a call to the POSIX functions setenv(), unsetenv(), and putenv() may invalidate the pointer returned by a previous call or modify the string obtained from a previous call.

Modifying the string returned by getenv invokes undefined behavior.

2) Same as (1), except that the values of the environment variable is written to the user-provided buffer value (unless null) and the number of bytes written is stored in the user-provided location *len (unless null). If the environment variable is not set in the environment, zero is written to *len (unless null) and '\0' is written to value[0] (unless null). In addition, the following errors are detected at runtime and call the currently installed constraint handler function:

name is a null pointer
valuesz is greater than RSIZE_MAX
value is a null pointer and valuesz is not zero

As all bounds-checked functions, getenv_s is only guaranteed to be available if __STDC_LIB_EXT1__ is defined by the implementation and if the user defines __STDC_WANT_LIB_EXT1__ to the integer constant 1 before including stdlib.h.

name	-	null-terminated character string identifying the name of the environmental variable to look for
len	-	pointer to a user-provided location where getenv_s will store the length of the environment variable
value	-	pointer to a user-provided character array where getenv_s will store the contents of the environment variable
valuesz	-	maximum number of characters that getenv_s is allowed to write to dest (size of the buffer)

[edit] Return value

1) character string identifying the value of the environmental variable or null pointer if such variable is not found.

2) zero if the environment variable was found, non-zero if it was not found of if a runtime constrant violation occurred. On any error, writes zero to *len (unless len is a null pointer).

[edit] Notes

On POSIX systems, the environment variables are also accessible through the global variable environ, declared as extern char **environ; in <unistd.h>, and through the optional third argument, envp, of the main function.

The call to getenv_s with a null pointer for value and zero for valuesz is used to determine the size of the buffer required to hold the entire result.

[edit] Example

Run this code

#include <stdio.h>
#include <stdlib.h>
 
int main(void)
{
    char *env_p = getenv("PATH");
    if (env_p)
        printf("PATH = %s\n", env_p);
}

Possible output:

PATH = /usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin

[edit] References

C11 standard (ISO/IEC 9899:2011):

7.22.4.6 The getenv function (p: 352-353)

K.3.6.2.1 The getenv_s function (p: 606-607)

C99 standard (ISO/IEC 9899:1999):

7.20.4.5 The getenv function (p: 317)

C89/C90 standard (ISO/IEC 9899:1990):

4.10.4.4 The getenv function

[edit] See also

C++ documentation for getenv

Language
headers
Type support
Dynamic memory management
Error handling
Program utilities
Variadic function support
Date and time utilities
Strings library
Algorithms
Numerics
Input/output support
Localization support
Thread support (C11)
Atomic operations (C11)
Technical Specifications