]>
Commit | Line | Data |
---|---|---|
fea681da | 1 | .\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) |
4e1927c6 | 2 | .\" and Copyright (C) 2007, 2012 Michael Kerrisk <mtk.manpages@gmail.com> |
fea681da | 3 | .\" |
93015253 | 4 | .\" %%%LICENSE_START(VERBATIM) |
fea681da MK |
5 | .\" Permission is granted to make and distribute verbatim copies of this |
6 | .\" manual provided the copyright notice and this permission notice are | |
7 | .\" preserved on all copies. | |
8 | .\" | |
9 | .\" Permission is granted to copy and distribute modified versions of this | |
10 | .\" manual under the conditions for verbatim copying, provided that the | |
11 | .\" entire resulting derived work is distributed under the terms of a | |
12 | .\" permission notice identical to this one. | |
c13182ef | 13 | .\" |
fea681da MK |
14 | .\" Since the Linux kernel and libraries are constantly changing, this |
15 | .\" manual page may be incorrect or out-of-date. The author(s) assume no | |
16 | .\" responsibility for errors or omissions, or for damages resulting from | |
17 | .\" the use of the information contained herein. The author(s) may not | |
18 | .\" have taken the same level of care in the production of this manual, | |
19 | .\" which is licensed free of charge, as they might when working | |
20 | .\" professionally. | |
c13182ef | 21 | .\" |
fea681da MK |
22 | .\" Formatted or processed versions of this manual, if unaccompanied by |
23 | .\" the source, must acknowledge the copyright and authors of this work. | |
4b72fb64 | 24 | .\" %%%LICENSE_END |
fea681da MK |
25 | .\" |
26 | .\" References consulted: | |
27 | .\" Linux libc source code | |
9f6d3345 | 28 | .\" Lewine's "POSIX Programmer's Guide" (O'Reilly & Associates, 1991) |
fea681da MK |
29 | .\" 386BSD man pages |
30 | .\" Modified Sat Jul 24 19:30:29 1993 by Rik Faith (faith@cs.unc.edu) | |
31 | .\" Modified Fri Feb 14 21:47:50 1997 by Andries Brouwer (aeb@cwi.nl) | |
32 | .\" | |
4b8c67d9 | 33 | .TH GETENV 3 2017-09-15 "GNU" "Linux Programmer's Manual" |
fea681da | 34 | .SH NAME |
4e1927c6 | 35 | getenv, secure_getenv \- get an environment variable |
fea681da MK |
36 | .SH SYNOPSIS |
37 | .nf | |
38 | .B #include <stdlib.h> | |
68e4db0a | 39 | .PP |
fea681da | 40 | .BI "char *getenv(const char *" name ); |
dbfe9c70 | 41 | .PP |
4e1927c6 | 42 | .BI "char *secure_getenv(const char *" name ); |
fea681da | 43 | .fi |
68e4db0a | 44 | .PP |
4e1927c6 MK |
45 | .in -4n |
46 | Feature Test Macro Requirements for glibc (see | |
47 | .BR feature_test_macros (7)): | |
48 | .in | |
68e4db0a | 49 | .PP |
760655c2 | 50 | .BR secure_getenv (): |
4e1927c6 | 51 | _GNU_SOURCE |
fea681da | 52 | .SH DESCRIPTION |
60a90ecd MK |
53 | The |
54 | .BR getenv () | |
9f6d3345 MK |
55 | function searches the environment list to find the |
56 | environment variable | |
57 | .IR name , | |
58 | and returns a pointer to the corresponding | |
59 | .I value | |
60 | string. | |
847e0d88 | 61 | .PP |
4e1927c6 MK |
62 | The GNU-specific |
63 | .BR secure_getenv () | |
64 | function is just like | |
65 | .BR getenv () | |
66 | except that it returns NULL in cases where "secure execution" is required. | |
67 | Secure execution is required if one of the following conditions | |
68 | was true when the program run by the calling process was loaded: | |
69 | .IP * 3 | |
70 | the process's effective user ID did not match its real user ID or | |
71 | the process's effective group ID did not match its real group ID | |
72 | (typically this is the result of executing a set-user-ID or | |
73 | set-group-ID program); | |
74 | .IP * | |
75 | the effective capability bit was set on the executable file; or | |
76 | .IP * | |
77 | the process has a nonempty permitted capability set. | |
78 | .PP | |
768b58c7 | 79 | Secure execution may also be required if triggered |
4e1927c6 | 80 | by some Linux security modules. |
847e0d88 | 81 | .PP |
4e1927c6 MK |
82 | The |
83 | .BR secure_getenv () | |
84 | function is intended for use in general-purpose libraries | |
85 | to avoid vulnerabilities that could occur if | |
86 | set-user-ID or set-group-ID programs accidentally | |
87 | trusted the environment. | |
47297adb | 88 | .SH RETURN VALUE |
60a90ecd MK |
89 | The |
90 | .BR getenv () | |
91 | function returns a pointer to the value in the | |
fea681da | 92 | environment, or NULL if there is no match. |
7484d5a7 MK |
93 | .SH VERSIONS |
94 | .BR secure_getenv () | |
95 | first appeared in glibc 2.17. | |
bdb80008 PH |
96 | .SH ATTRIBUTES |
97 | For an explanation of the terms used in this section, see | |
98 | .BR attributes (7). | |
99 | .TS | |
100 | allbox; | |
101 | lbw25 lb lb | |
102 | l l l. | |
103 | Interface Attribute Value | |
104 | T{ | |
105 | .BR getenv (), | |
106 | .BR secure_getenv () | |
107 | T} Thread safety MT-Safe env | |
108 | .TE | |
47297adb | 109 | .SH CONFORMING TO |
4e1927c6 | 110 | .BR getenv (): |
8ae90f8e | 111 | POSIX.1-2001, POSIX.1-2008, C89, C99, SVr4, 4.3BSD. |
847e0d88 | 112 | .PP |
4e1927c6 MK |
113 | .BR secure_getenv () |
114 | is a GNU extension. | |
9f6d3345 MK |
115 | .SH NOTES |
116 | The strings in the environment list are of the form \fIname=value\fP. | |
847e0d88 | 117 | .PP |
9f6d3345 MK |
118 | As typically implemented, |
119 | .BR getenv () | |
120 | returns a pointer to a string within the environment list. | |
121 | The caller must take care not to modify this string, | |
122 | since that would change the environment of the process. | |
847e0d88 | 123 | .PP |
9f6d3345 MK |
124 | The implementation of |
125 | .BR getenv () | |
126 | is not required to be reentrant. | |
127 | The string pointed to by the return value of | |
128 | .BR getenv () | |
129 | may be statically allocated, | |
130 | and can be modified by a subsequent call to | |
131 | .BR getenv (), | |
132 | .BR putenv (3), | |
133 | .BR setenv (3), | |
134 | or | |
135 | .BR unsetenv (3). | |
847e0d88 | 136 | .PP |
4e1927c6 MK |
137 | The "secure execution" mode of |
138 | .BR secure_getenv () | |
139 | is controlled by the | |
140 | .B AT_SECURE | |
141 | flag contained in the auxiliary vector passed from the kernel to user space. | |
47297adb | 142 | .SH SEE ALSO |
fea681da | 143 | .BR clearenv (3), |
80380b8e | 144 | .BR getauxval (3), |
fea681da MK |
145 | .BR putenv (3), |
146 | .BR setenv (3), | |
147 | .BR unsetenv (3), | |
4e1927c6 | 148 | .BR capabilities (7), |
aa949e2d | 149 | .BR environ (7) |