Debian Codegraph @

upstream/debian-unstable/man3/putenv.3

raw
1 '\" t
2 .\" Copyright 1993, David Metcalfe <[email protected]>
3 .\" Copyright, the authors of the Linux man-pages project
4 .\"
5 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
6 .\"
7 .TH putenv 3 2026-02-08 "Linux man-pages 6.18"
8 .SH NAME
9 putenv \- change or add an environment variable
10 .SH LIBRARY
11 Standard C library
12 .RI ( libc ,\~ \-lc )
13 .SH SYNOPSIS
14 .nf
15 .B #include <stdlib.h>
16 .P
17 .BI "int putenv(char *" string );
18 .\" Not: const char *
19 .fi
20 .P
21 .RS -4
22 Feature Test Macro Requirements for glibc (see
23 .BR feature_test_macros (7)):
24 .RE
25 .P
26 .BR putenv ():
27 .nf
28 _XOPEN_SOURCE
29 || /* glibc >= 2.19: */ _DEFAULT_SOURCE
30 || /* glibc <= 2.19: */ _SVID_SOURCE
31 .fi
32 .SH DESCRIPTION
33 The
34 .BR putenv ()
35 function adds or changes the value of environment
36 variables.
37 The argument
38 .I string
39 is of the form
40 .IR name = value .
41 If
42 .I name
43 does not already exist in the environment, then
44 .I string
45 is added to the environment.
46 If
47 .I name
48 does exist,
49 then the value of
50 .I name
51 in the environment is changed to
52 .IR value .
53 The string pointed to by
54 .I string
55 becomes part of the environment,
56 so altering the string changes the environment.
57 .SH RETURN VALUE
58 The
59 .BR putenv ()
60 function returns zero on success.
61 On failure, it returns a nonzero value, and
62 .I errno
63 is set to indicate the error.
64 .SH ERRORS
65 .TP
66 .B ENOMEM
67 Insufficient space to allocate new environment.
68 .SH ATTRIBUTES
69 For an explanation of the terms used in this section, see
70 .BR attributes (7).
71 .TS
72 allbox;
73 lbx lb lb
74 l l l.
75 Interface Attribute Value
76 T{
77 .na
78 .nh
79 .BR putenv ()
80 T} Thread safety MT-Unsafe const:env
81 .TE
82 .SH STANDARDS
83 POSIX.1-2008.
84 .SH HISTORY
85 POSIX.1-2001, SVr2, 4.3BSD-Reno.
86 .P
87 The
88 .BR putenv ()
89 function is not required to be reentrant, and the
90 one in glibc 2.0 is not, but the glibc 2.1 version is.
91 .\" .P
92 .\" Description for libc4, libc5, glibc:
93 .\" If the argument
94 .\" .I string
95 .\" is of the form
96 .\" .IR name ,
97 .\" and does not contain an \[aq]=\[aq] character, then the variable
98 .\" .I name
99 .\" is removed from the environment.
100 .\" If
101 .\" .BR putenv ()
102 .\" has to allocate a new array
103 .\" .IR environ ,
104 .\" and the previous array was also allocated by
105 .\" .BR putenv (),
106 .\" then it will be freed.
107 .\" In no case will the old storage associated
108 .\" to the environment variable itself be freed.
109 .P
110 Since glibc 2.1.2, the glibc implementation conforms to SUSv2:
111 the pointer
112 .I string
113 given to
114 .BR putenv ()
115 is used.
116 In particular, this string becomes part of the environment;
117 changing it later will change the environment.
118 (Thus, it is an error to call
119 .BR putenv ()
120 with an automatic variable
121 as the argument, then return from the calling function while
122 .I string
123 is still part of the environment.)
124 However, from glibc 2.0 to glibc 2.1.1, it differs:
125 a copy of the string is used.
126 On the one hand this causes a memory leak, and on the other hand
127 it violates SUSv2.
128 .P
129 The 4.3BSD-Reno version, like glibc 2.0, uses a copy;
130 this is fixed in all modern BSDs.
131 .P
132 SUSv2 removes the
133 .I const
134 from the prototype, and so does glibc 2.1.3.
135 .P
136 The GNU C library implementation provides a nonstandard extension.
137 If
138 .I string
139 does not include an equal sign:
140 .P
141 .in +4n
142 .EX
143 putenv("NAME");
144 .EE
145 .in
146 .P
147 then the named variable is removed from the caller's environment.
148 .SH SEE ALSO
149 .BR clearenv (3),
150 .BR getenv (3),
151 .BR setenv (3),
152 .BR unsetenv (3),
153 .BR environ (7)