Debian Codegraph @

upstream/debian-unstable/man3/setenv.3

raw
1 '\" t
2 .\" Copyright 1993, David Metcalfe <[email protected]>
3 .\" Copyright 2004-2007, Michael Kerrisk <[email protected]>
4 .\" Copyright, the authors of the Linux man-pages project
5 .\"
6 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
7 .\"
8 .TH setenv 3 2026-02-08 "Linux man-pages 6.18"
9 .SH NAME
10 setenv \- change or add an environment variable
11 .SH LIBRARY
12 Standard C library
13 .RI ( libc ,\~ \-lc )
14 .SH SYNOPSIS
15 .nf
16 .B #include <stdlib.h>
17 .P
18 .BI "int setenv(const char *" name ", const char *" value ", int " overwrite );
19 .BI "int unsetenv(const char *" name );
20 .fi
21 .P
22 .RS -4
23 Feature Test Macro Requirements for glibc (see
24 .BR feature_test_macros (7)):
25 .RE
26 .P
27 .BR setenv (),
28 .BR unsetenv ():
29 .nf
30 _POSIX_C_SOURCE >= 200112L
31 || /* glibc <= 2.19: */ _BSD_SOURCE
32 .fi
33 .SH DESCRIPTION
34 The
35 .BR setenv ()
36 function adds the variable
37 .I name
38 to the
39 environment with the value
40 .IR value ,
41 if
42 .I name
43 does not
44 already exist.
45 If
46 .I name
47 does exist in the environment, then
48 its value is changed to
49 .I value
50 if
51 .I overwrite
52 is nonzero;
53 if
54 .I overwrite
55 is zero, then the value of
56 .I name
57 is not changed (and
58 .BR setenv ()
59 returns a success status).
60 This function makes copies of the strings pointed to by
61 .I name
62 and
63 .I value
64 (by contrast with
65 .BR putenv (3)).
66 .P
67 The
68 .BR unsetenv ()
69 function deletes the variable
70 .I name
71 from
72 the environment.
73 If
74 .I name
75 does not exist in the environment,
76 then the function succeeds, and the environment is unchanged.
77 .SH RETURN VALUE
78 .BR setenv ()
79 and
80 .BR unsetenv ()
81 functions return zero on success,
82 or \-1 on error, with
83 .I errno
84 set to indicate the error.
85 .SH ERRORS
86 .TP
87 .B EINVAL
88 .I name
89 is NULL, points to a string of length 0,
90 or contains an \[aq]=\[aq] character.
91 .TP
92 .B ENOMEM
93 Insufficient memory to add a new variable to the environment.
94 .SH ATTRIBUTES
95 For an explanation of the terms used in this section, see
96 .BR attributes (7).
97 .TS
98 allbox;
99 lbx lb lb
100 l l l.
101 Interface Attribute Value
102 T{
103 .na
104 .nh
105 .BR setenv (),
106 .BR unsetenv ()
107 T} Thread safety MT-Unsafe const:env
108 .TE
109 .SH STANDARDS
110 POSIX.1-2008.
111 .SH HISTORY
112 POSIX.1-2001, 4.3BSD.
113 .P
114 Prior to glibc 2.2.2,
115 .BR unsetenv ()
116 was prototyped
117 as returning
118 .IR void ;
119 more recent glibc versions follow the
120 POSIX.1-compliant prototype shown in the SYNOPSIS.
121 .SH CAVEATS
122 POSIX.1 does not require
123 .BR setenv ()
124 or
125 .BR unsetenv ()
126 to be reentrant.
127 .SH BUGS
128 POSIX.1 specifies that if
129 .I name
130 contains an \[aq]=\[aq] character, then
131 .BR setenv ()
132 should fail with the error
133 .BR EINVAL ;
134 however, versions of glibc before glibc 2.3.4 allowed an \[aq]=\[aq] sign in
135 .IR name .
136 .SH SEE ALSO
137 .BR clearenv (3),
138 .BR getenv (3),
139 .BR putenv (3),
140 .BR environ (7)