summaryrefslogtreecommitdiffstats
path: root/man3/getenv.3
diff options
context:
space:
mode:
Diffstat (limited to '')
-rw-r--r--man3/getenv.3142
1 files changed, 142 insertions, 0 deletions
diff --git a/man3/getenv.3 b/man3/getenv.3
new file mode 100644
index 0000000..705eb43
--- /dev/null
+++ b/man3/getenv.3
@@ -0,0 +1,142 @@
+'\" t
+.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk)
+.\" and Copyright (C) 2007, 2012 Michael Kerrisk <mtk.manpages@gmail.com>
+.\"
+.\" SPDX-License-Identifier: Linux-man-pages-copyleft
+.\"
+.\" References consulted:
+.\" Linux libc source code
+.\" Lewine's "POSIX Programmer's Guide" (O'Reilly & Associates, 1991)
+.\" 386BSD man pages
+.\" Modified Sat Jul 24 19:30:29 1993 by Rik Faith (faith@cs.unc.edu)
+.\" Modified Fri Feb 14 21:47:50 1997 by Andries Brouwer (aeb@cwi.nl)
+.\"
+.TH getenv 3 2023-07-20 "Linux man-pages 6.05.01"
+.SH NAME
+getenv, secure_getenv \- get an environment variable
+.SH LIBRARY
+Standard C library
+.RI ( libc ", " \-lc )
+.SH SYNOPSIS
+.nf
+.B #include <stdlib.h>
+.PP
+.BI "char *getenv(const char *" name );
+.BI "char *secure_getenv(const char *" name );
+.fi
+.PP
+.RS -4
+Feature Test Macro Requirements for glibc (see
+.BR feature_test_macros (7)):
+.RE
+.PP
+.BR secure_getenv ():
+.nf
+ _GNU_SOURCE
+.fi
+.SH DESCRIPTION
+The
+.BR getenv ()
+function searches the environment list to find the
+environment variable
+.IR name ,
+and returns a pointer to the corresponding
+.I value
+string.
+.PP
+The GNU-specific
+.BR secure_getenv ()
+function is just like
+.BR getenv ()
+except that it returns NULL in cases where "secure execution" is required.
+Secure execution is required if one of the following conditions
+was true when the program run by the calling process was loaded:
+.IP \[bu] 3
+the process's effective user ID did not match its real user ID or
+the process's effective group ID did not match its real group ID
+(typically this is the result of executing a set-user-ID or
+set-group-ID program);
+.IP \[bu]
+the effective capability bit was set on the executable file; or
+.IP \[bu]
+the process has a nonempty permitted capability set.
+.PP
+Secure execution may also be required if triggered
+by some Linux security modules.
+.PP
+The
+.BR secure_getenv ()
+function is intended for use in general-purpose libraries
+to avoid vulnerabilities that could occur if
+set-user-ID or set-group-ID programs accidentally
+trusted the environment.
+.SH RETURN VALUE
+The
+.BR getenv ()
+function returns a pointer to the value in the
+environment, or NULL if there is no match.
+.SH ATTRIBUTES
+For an explanation of the terms used in this section, see
+.BR attributes (7).
+.TS
+allbox;
+lbx lb lb
+l l l.
+Interface Attribute Value
+T{
+.na
+.nh
+.BR getenv (),
+.BR secure_getenv ()
+T} Thread safety MT-Safe env
+.TE
+.sp 1
+.SH STANDARDS
+.TP
+.BR getenv ()
+C11, POSIX.1-2008.
+.TP
+.BR secure_getenv ()
+GNU.
+.SH HISTORY
+.TP
+.BR getenv ()
+POSIX.1-2001, C89, C99, SVr4, 4.3BSD.
+.TP
+.BR secure_getenv ()
+glibc 2.17.
+.SH NOTES
+The strings in the environment list are of the form \fIname=value\fP.
+.PP
+As typically implemented,
+.BR getenv ()
+returns a pointer to a string within the environment list.
+The caller must take care not to modify this string,
+since that would change the environment of the process.
+.PP
+The implementation of
+.BR getenv ()
+is not required to be reentrant.
+The string pointed to by the return value of
+.BR getenv ()
+may be statically allocated,
+and can be modified by a subsequent call to
+.BR getenv (),
+.BR putenv (3),
+.BR setenv (3),
+or
+.BR unsetenv (3).
+.PP
+The "secure execution" mode of
+.BR secure_getenv ()
+is controlled by the
+.B AT_SECURE
+flag contained in the auxiliary vector passed from the kernel to user space.
+.SH SEE ALSO
+.BR clearenv (3),
+.BR getauxval (3),
+.BR putenv (3),
+.BR setenv (3),
+.BR unsetenv (3),
+.BR capabilities (7),
+.BR environ (7)