Go to main content

man pages section 3: Basic Library Functions

Exit Print View

Updated: Wednesday, July 27, 2022
 
 

getenv(3C)

Name

getenv, secure_getenv, getenv_s - return value for environment name

Synopsis

#include <stdlib.h>

char *getenv(const char *name);
char *secure_getenv(const char *name);
#define __STDC_WANT_LIB_EXT1__ 1
#include <stdlib.h>

errno_t getenv_s(size_t *restrict len, char *restrict value,
	size_t maxsize, const char *restrict name);
  

Description

The getenv() function searches the environment list (see environ(7)) for a string of the form name=value and, if the string is present, returns a pointer to the value in the current environment.

The secure_getenv() function behaves like getenv() except that it returns a null pointer if the issetugid() calls returns a non-zero value. For more information, see the issetugid(2) man page.

The getenv_s() function is part of the bounds checking interfaces specified in the C11 standard, Annex K. It behaves in a manner similar to the getenv() function, but with differing parameters and return type in order to provide additional safety checks in the form of explicit runtime-constraints as defined in the C11 standard. See runtime_constraint_handler(3C) and INCITS/ISO/IEC 9899:2011.

Return Values

If successful, getenv() and secure_getenv() return a pointer to the value in the current environment; otherwise, they return a null pointer.

If the specified name is found and the associated string was successfully stored in value, the getenv_s() function returns zero; otherwise, it returns a non-zero value.

EINVAL

Null pointer is passed

ERANGE

size argument is not a valid value

ENOENT

No such file or directory

Usage

The getenv() and secure_getenv() functions can be safely called from a multithreaded application. Care must be exercised when using either getenv() or secure_getenv() functions with putenv(3C) in a multithreaded application. These functions examine and modify the environment list, which is shared by all threads in an application. The system prevents the list from being accessed simultaneously by two different threads. It does not, however, prevent two threads from successively accessing the environment list using getenv(), secure_getenv(), or putenv(3C).

The secure_getenv() function is intended for use in general-purpose libraries to avoid vulnerabilities that could occur if programs with raised privilege accidentally trusted the environment.

Attributes

See attributes(7) for descriptions of the following attributes:

ATTRIBUTE TYPE
ATTRIBUTE VALUE
Interface Stability
Committed
MT-Level
See below
Standard
See below

The getenv() and secure_getenv() functions can be used safely in multithreaded applications, with the caveats noted above.

The getenv_s() function cannot be used safely in a multithreaded application due to the runtime constraint handler. For more information, see the runtime_constraint_handler(3C) man page.

The getenv() function is specified by the ISO C and XPG standards. The getenv_s() function is specified by the ISO C11 standard. The secure_getenv() function is not specified by any current standards. See standards(7) for further details.

See Also

exec(2), issetugid(2), putenv(3C), attributes(7), environ(7), standards(7), runtime_constraint_handler(3C)

HISTORY

The getenv_s() function was added to Oracle Solaris in the 11.4 release.

The secure_getenv() function was added to Oracle Solaris in the 11.3 SRU 10 release.