2 .\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk)
4 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
6 .\" References consulted:
7 .\" Linux libc source code
8 .\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991)
10 .\" Single UNIX Specification, Version 2
11 .\" Modified Thu Apr 8 15:00:12 1993, David Metcalfe
12 .\" Modified Sat Jul 24 18:44:45 1993, Rik Faith (faith@cs.unc.edu)
13 .\" Modified Fri Feb 14 21:47:50 1997 by Andries Brouwer (aeb@cwi.nl)
14 .\" Modified Mon Oct 11 11:11:11 1999 by Andries Brouwer (aeb@cwi.nl)
15 .\" Modified Wed Nov 10 00:02:26 1999 by Andries Brouwer (aeb@cwi.nl)
16 .\" Modified Sun May 20 22:17:20 2001 by Andries Brouwer (aeb@cwi.nl)
17 .TH putenv 3 (date) "Linux man-pages (unreleased)"
19 putenv \- change or add an environment variable
22 .RI ( libc ", " \-lc )
25 .B #include <stdlib.h>
27 .BI "int putenv(char *" string );
32 Feature Test Macro Requirements for glibc (see
33 .BR feature_test_macros (7)):
39 || /* glibc >= 2.19: */ _DEFAULT_SOURCE
40 || /* glibc <= 2.19: */ _SVID_SOURCE
45 function adds or changes the value of environment
47 The argument \fIstring\fP is of the form \fIname\fP=\fIvalue\fP.
48 If \fIname\fP does not already exist in the environment, then
49 \fIstring\fP is added to the environment.
50 If \fIname\fP does exist,
51 then the value of \fIname\fP in the environment is changed to
53 The string pointed to by \fIstring\fP becomes part of the environment,
54 so altering the string changes the environment.
58 function returns zero on success.
59 On failure, it returns a nonzero value, and
61 is set to indicate the error.
65 Insufficient space to allocate new environment.
67 For an explanation of the terms used in this section, see
73 Interface Attribute Value
78 T} Thread safety MT-Unsafe const:env
83 POSIX.1-2001, SVr2, 4.3BSD-Reno.
87 function is not required to be reentrant, and the
88 one in glibc 2.0 is not, but the glibc 2.1 version is.
90 .\" Description for libc4, libc5, glibc:
91 .\" If the argument \fIstring\fP is of the form \fIname\fP,
92 .\" and does not contain an \[aq]=\[aq] character, then the variable \fIname\fP
93 .\" is removed from the environment.
96 .\" has to allocate a new array \fIenviron\fP,
97 .\" and the previous array was also allocated by
99 .\" then it will be freed.
100 .\" In no case will the old storage associated
101 .\" to the environment variable itself be freed.
103 Since glibc 2.1.2, the glibc implementation conforms to SUSv2:
104 the pointer \fIstring\fP given to
107 In particular, this string becomes part of the environment;
108 changing it later will change the environment.
109 (Thus, it is an error to call
111 with an automatic variable
112 as the argument, then return from the calling function while \fIstring\fP
113 is still part of the environment.)
114 However, from glibc 2.0 to glibc 2.1.1, it differs:
115 a copy of the string is used.
116 On the one hand this causes a memory leak, and on the other hand
119 The 4.3BSD-Reno version, like glibc 2.0, uses a copy;
120 this is fixed in all modern BSDs.
122 SUSv2 removes the \fIconst\fP from the prototype, and so does glibc 2.1.3.
124 The GNU C library implementation provides a nonstandard extension.
127 does not include an equal sign:
135 then the named variable is removed from the caller's environment.