]>
Commit | Line | Data |
---|---|---|
a1eaacb1 | 1 | '\" t |
fea681da | 2 | .\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) |
31cc8387 | 3 | .\" and Copyright (C) 2004, 2007 Michael Kerrisk <mtk.manpages@gmail.com> |
fea681da | 4 | .\" |
5fbde956 | 5 | .\" SPDX-License-Identifier: Linux-man-pages-copyleft |
fea681da MK |
6 | .\" |
7 | .\" References consulted: | |
8 | .\" Linux libc source code | |
9 | .\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) | |
10 | .\" 386BSD man pages | |
11 | .\" Modified Sat Jul 24 18:20:58 1993 by Rik Faith (faith@cs.unc.edu) | |
12 | .\" Modified Fri Feb 14 21:47:50 1997 by Andries Brouwer (aeb@cwi.nl) | |
c11b1abf | 13 | .\" Modified 9 Jun 2004, Michael Kerrisk <mtk.manpages@gmail.com> |
fea681da | 14 | .\" Changed unsetenv() prototype; added EINVAL error |
c8f2dd47 | 15 | .\" Noted nonstandard behavior of setenv() if name contains '=' |
279d6eea | 16 | .\" 2005-08-12, mtk, glibc 2.3.4 fixed the "name contains '='" bug |
fea681da | 17 | .\" |
4c1c5274 | 18 | .TH setenv 3 (date) "Linux man-pages (unreleased)" |
fea681da MK |
19 | .SH NAME |
20 | setenv \- change or add an environment variable | |
09672b8d AC |
21 | .SH LIBRARY |
22 | Standard C library | |
8fc3b2cf | 23 | .RI ( libc ", " \-lc ) |
fea681da MK |
24 | .SH SYNOPSIS |
25 | .nf | |
26 | .B #include <stdlib.h> | |
68e4db0a | 27 | .PP |
fea681da | 28 | .BI "int setenv(const char *" name ", const char *" value ", int " overwrite ); |
fea681da MK |
29 | .BI "int unsetenv(const char *" name ); |
30 | .fi | |
68e4db0a | 31 | .PP |
d39ad78f | 32 | .RS -4 |
cc4615cc MK |
33 | Feature Test Macro Requirements for glibc (see |
34 | .BR feature_test_macros (7)): | |
d39ad78f | 35 | .RE |
68e4db0a | 36 | .PP |
cc4615cc MK |
37 | .BR setenv (), |
38 | .BR unsetenv (): | |
9d2adbae | 39 | .nf |
5c10d2c5 | 40 | _POSIX_C_SOURCE >= 200112L |
75c018a1 | 41 | || /* glibc <= 2.19: */ _BSD_SOURCE |
9d2adbae | 42 | .fi |
fea681da | 43 | .SH DESCRIPTION |
60a90ecd MK |
44 | The |
45 | .BR setenv () | |
c6fa0841 MK |
46 | function adds the variable |
47 | .I name | |
48 | to the | |
49 | environment with the value | |
50 | .IR value , | |
51 | if | |
52 | .I name | |
53 | does not | |
c13182ef | 54 | already exist. |
c6fa0841 MK |
55 | If |
56 | .I name | |
57 | does exist in the environment, then | |
58 | its value is changed to | |
1ae6b2c7 | 59 | .I value |
c6fa0841 MK |
60 | if |
61 | .I overwrite | |
62 | is nonzero; | |
63 | if | |
1ae6b2c7 | 64 | .I overwrite |
c6fa0841 MK |
65 | is zero, then the value of |
66 | .I name | |
779e42d0 MK |
67 | is not changed (and |
68 | .BR setenv () | |
69 | returns a success status). | |
f3268285 MK |
70 | This function makes copies of the strings pointed to by |
71 | .I name | |
72 | and | |
73 | .I value | |
74 | (by contrast with | |
75 | .BR putenv (3)). | |
fea681da | 76 | .PP |
60a90ecd MK |
77 | The |
78 | .BR unsetenv () | |
c6fa0841 MK |
79 | function deletes the variable |
80 | .I name | |
81 | from | |
fea681da | 82 | the environment. |
f3268285 MK |
83 | If |
84 | .I name | |
85 | does not exist in the environment, | |
86 | then the function succeeds, and the environment is unchanged. | |
47297adb | 87 | .SH RETURN VALUE |
60a90ecd | 88 | .BR setenv () |
483368b3 | 89 | and |
60a90ecd | 90 | .BR unsetenv () |
483368b3 | 91 | functions return zero on success, |
fea681da MK |
92 | or \-1 on error, with |
93 | .I errno | |
855d489a | 94 | set to indicate the error. |
47297adb | 95 | .SH ERRORS |
fea681da MK |
96 | .TP |
97 | .B EINVAL | |
98 | .I name | |
2a4b81ff | 99 | is NULL, points to a string of length 0, |
b957f81f | 100 | or contains an \[aq]=\[aq] character. |
2a4b81ff MK |
101 | .TP |
102 | .B ENOMEM | |
103 | Insufficient memory to add a new variable to the environment. | |
6d682990 MS |
104 | .SH ATTRIBUTES |
105 | For an explanation of the terms used in this section, see | |
106 | .BR attributes (7). | |
107 | .TS | |
108 | allbox; | |
c466875e | 109 | lbx lb lb |
6d682990 MS |
110 | l l l. |
111 | Interface Attribute Value | |
112 | T{ | |
9e54434e BR |
113 | .na |
114 | .nh | |
6d682990 MS |
115 | .BR setenv (), |
116 | .BR unsetenv () | |
117 | T} Thread safety MT-Unsafe const:env | |
118 | .TE | |
c466875e | 119 | .sp 1 |
3113c7f3 | 120 | .SH STANDARDS |
4131356c AC |
121 | POSIX.1-2008. |
122 | .SH HISTORY | |
123 | POSIX.1-2001, 4.3BSD. | |
847e0d88 | 124 | .PP |
60a90ecd MK |
125 | Prior to glibc 2.2.2, |
126 | .BR unsetenv () | |
127 | was prototyped | |
c6fa0841 MK |
128 | as returning |
129 | .IR void ; | |
130 | more recent glibc versions follow the | |
246d0d44 | 131 | POSIX.1-compliant prototype shown in the SYNOPSIS. |
4131356c AC |
132 | .SH CAVEATS |
133 | POSIX.1 does not require | |
134 | .BR setenv () | |
135 | or | |
136 | .BR unsetenv () | |
137 | to be reentrant. | |
fea681da | 138 | .SH BUGS |
246d0d44 | 139 | POSIX.1 specifies that if |
fea681da | 140 | .I name |
b957f81f | 141 | contains an \[aq]=\[aq] character, then |
fea681da MK |
142 | .BR setenv () |
143 | should fail with the error | |
144 | .BR EINVAL ; | |
b957f81f | 145 | however, versions of glibc before glibc 2.3.4 allowed an \[aq]=\[aq] sign in |
fea681da | 146 | .IR name . |
47297adb | 147 | .SH SEE ALSO |
fea681da MK |
148 | .BR clearenv (3), |
149 | .BR getenv (3), | |
150 | .BR putenv (3), | |
aa949e2d | 151 | .BR environ (7) |