1.\" Copyright (c) 1988, 1991, 1993
2.\" The Regents of the University of California. All rights reserved.
3.\"
4.\" This code is derived from software contributed to Berkeley by
5.\" the American National Standards Committee X3, on Information
6.\" Processing Systems.
7.\"
8.\" Redistribution and use in source and binary forms, with or without
9.\" modification, are permitted provided that the following conditions
10.\" are met:
11.\" 1. Redistributions of source code must retain the above copyright
12.\" notice, this list of conditions and the following disclaimer.
13.\" 2. Redistributions in binary form must reproduce the above copyright
14.\" notice, this list of conditions and the following disclaimer in the
15.\" documentation and/or other materials provided with the distribution.
16.\" 4. Neither the name of the University nor the names of its contributors
17.\" may be used to endorse or promote products derived from this software
18.\" without specific prior written permission.
19.\"
20.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
21.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
22.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
23.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
24.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
25.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
26.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
27.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
28.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
29.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
30.\" SUCH DAMAGE.
31.\"
32.\" @(#)getenv.3 8.2 (Berkeley) 12/11/93
| 1.\" Copyright (c) 1988, 1991, 1993
2.\" The Regents of the University of California. All rights reserved.
3.\"
4.\" This code is derived from software contributed to Berkeley by
5.\" the American National Standards Committee X3, on Information
6.\" Processing Systems.
7.\"
8.\" Redistribution and use in source and binary forms, with or without
9.\" modification, are permitted provided that the following conditions
10.\" are met:
11.\" 1. Redistributions of source code must retain the above copyright
12.\" notice, this list of conditions and the following disclaimer.
13.\" 2. Redistributions in binary form must reproduce the above copyright
14.\" notice, this list of conditions and the following disclaimer in the
15.\" documentation and/or other materials provided with the distribution.
16.\" 4. Neither the name of the University nor the names of its contributors
17.\" may be used to endorse or promote products derived from this software
18.\" without specific prior written permission.
19.\"
20.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
21.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
22.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
23.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
24.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
25.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
26.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
27.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
28.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
29.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
30.\" SUCH DAMAGE.
31.\"
32.\" @(#)getenv.3 8.2 (Berkeley) 12/11/93
|
33.\" $FreeBSD: head/lib/libc/stdlib/getenv.3 169146 2007-04-30 19:37:10Z ache $
| 33.\" $FreeBSD: head/lib/libc/stdlib/getenv.3 169177 2007-05-01 16:02:44Z ache $
|
34.\"
| 34.\"
|
35.Dd April 30, 2007
| 35.Dd October 12, 2006
|
36.Dt GETENV 3
37.Os
38.Sh NAME
39.Nm getenv ,
40.Nm putenv ,
41.Nm setenv ,
42.Nm unsetenv
43.Nd environment variable functions
44.Sh LIBRARY
45.Lb libc
46.Sh SYNOPSIS
47.In stdlib.h
48.Ft char *
49.Fn getenv "const char *name"
50.Ft int
51.Fn setenv "const char *name" "const char *value" "int overwrite"
52.Ft int
| 36.Dt GETENV 3
37.Os
38.Sh NAME
39.Nm getenv ,
40.Nm putenv ,
41.Nm setenv ,
42.Nm unsetenv
43.Nd environment variable functions
44.Sh LIBRARY
45.Lb libc
46.Sh SYNOPSIS
47.In stdlib.h
48.Ft char *
49.Fn getenv "const char *name"
50.Ft int
51.Fn setenv "const char *name" "const char *value" "int overwrite"
52.Ft int
|
53.Fn putenv "char *string"
54.Ft int
| 53.Fn putenv "const char *string"
54.Ft void
|
55.Fn unsetenv "const char *name"
56.Sh DESCRIPTION
57These functions set, unset and fetch environment variables from the
58host
59.Em environment list .
| 55.Fn unsetenv "const char *name"
56.Sh DESCRIPTION
57These functions set, unset and fetch environment variables from the
58host
59.Em environment list .
|
| 60For compatibility with differing environment conventions,
61the given arguments
62.Fa name
63and
64.Fa value
65may be appended and prepended,
66respectively,
67with an equal sign
68.Dq Li \&= .
|
60.Pp
61The
62.Fn getenv
63function obtains the current value of the environment variable,
64.Fa name .
65The application should not modify the string pointed
66to by the
67.Fn getenv
68function.
69.Pp
70The
71.Fn setenv
72function inserts or resets the environment variable
73.Fa name
74in the current environment list.
75If the variable
76.Fa name
77does not exist in the list,
78it is inserted with the given
79.Fa value .
80If the variable does exist, the argument
81.Fa overwrite
82is tested; if
83.Fa overwrite
84is zero, the
85variable is not reset, otherwise it is reset
86to the given
87.Fa value .
88.Pp
89The
90.Fn putenv
| 69.Pp
70The
71.Fn getenv
72function obtains the current value of the environment variable,
73.Fa name .
74The application should not modify the string pointed
75to by the
76.Fn getenv
77function.
78.Pp
79The
80.Fn setenv
81function inserts or resets the environment variable
82.Fa name
83in the current environment list.
84If the variable
85.Fa name
86does not exist in the list,
87it is inserted with the given
88.Fa value .
89If the variable does exist, the argument
90.Fa overwrite
91is tested; if
92.Fa overwrite
93is zero, the
94variable is not reset, otherwise it is reset
95to the given
96.Fa value .
97.Pp
98The
99.Fn putenv
|
91function takes an argument of the form ``name=value'' and
92puts it directly into the current environment,
93so altering the argument shall change the environment.
94If the variable
95.Fa name
96does not exist in the list,
97it is inserted with the given
98.Fa value .
99If the variable
100.Fa name
101does exist, it is reset to the given
102.Fa value .
| 100function takes an argument of the form ``name=value'' and is
101equivalent to:
102.Bd -literal -offset indent
103setenv(name, value, 1);
104.Ed
|
103.Pp
104The
105.Fn unsetenv
106function
107deletes all instances of the variable name pointed to by
108.Fa name
109from the list.
110.Sh RETURN VALUES
111The
112.Fn getenv
113function returns the value of the environment variable as a
114.Dv NUL Ns
115-terminated string.
116If the variable
117.Fa name
118is not in the current environment,
119.Dv NULL
120is returned.
121.Pp
| 105.Pp
106The
107.Fn unsetenv
108function
109deletes all instances of the variable name pointed to by
110.Fa name
111from the list.
112.Sh RETURN VALUES
113The
114.Fn getenv
115function returns the value of the environment variable as a
116.Dv NUL Ns
117-terminated string.
118If the variable
119.Fa name
120is not in the current environment,
121.Dv NULL
122is returned.
123.Pp
|
122.Rv -std setenv putenv unsetenv
| 124.Rv -std setenv putenv
|
123.Sh ERRORS
124.Bl -tag -width Er
| 125.Sh ERRORS
126.Bl -tag -width Er
|
125.It Bq Er EINVAL
126The function
127.Fn setenv
128or
129.Fn unsetenv
130failed because the
131.Fa name
132is a
133.Dv NULL
134pointer, points to an empty string, or points to a string containing an
135.Dq Li \&=
136character.
| |
137.It Bq Er ENOMEM
138The function
139.Fn setenv
140or
141.Fn putenv
142failed because they were unable to allocate memory for the environment.
143.El
144.Sh SEE ALSO
145.Xr csh 1 ,
146.Xr sh 1 ,
147.Xr execve 2 ,
148.Xr environ 7
149.Sh STANDARDS
150The
151.Fn getenv
152function conforms to
153.St -isoC .
| 127.It Bq Er ENOMEM
128The function
129.Fn setenv
130or
131.Fn putenv
132failed because they were unable to allocate memory for the environment.
133.El
134.Sh SEE ALSO
135.Xr csh 1 ,
136.Xr sh 1 ,
137.Xr execve 2 ,
138.Xr environ 7
139.Sh STANDARDS
140The
141.Fn getenv
142function conforms to
143.St -isoC .
|
154The
155.Fn setenv ,
156.Fn putenv
157and
158.Fn unsetenv
159functions conforms to
160.St -p1003.1-2001 .
| |
161.Sh HISTORY
162The functions
163.Fn setenv
164and
165.Fn unsetenv
166appeared in
167.At v7 .
168The
169.Fn putenv
170function appeared in
171.Bx 4.3 Reno .
172.Sh BUGS
173Successive calls to
174.Fn setenv
175or
176.Fn putenv
177assigning a differently sized
178.Fa value
179to the same
180.Fa name
181will result in a memory leak.
182The
183.Fx
184semantics for these functions
185(namely, that the contents of
186.Fa value
187are copied and that old values remain accessible indefinitely) make this
188bug unavoidable.
189Future versions may eliminate one or both of these
190semantic guarantees in order to fix the bug.
| 144.Sh HISTORY
145The functions
146.Fn setenv
147and
148.Fn unsetenv
149appeared in
150.At v7 .
151The
152.Fn putenv
153function appeared in
154.Bx 4.3 Reno .
155.Sh BUGS
156Successive calls to
157.Fn setenv
158or
159.Fn putenv
160assigning a differently sized
161.Fa value
162to the same
163.Fa name
164will result in a memory leak.
165The
166.Fx
167semantics for these functions
168(namely, that the contents of
169.Fa value
170are copied and that old values remain accessible indefinitely) make this
171bug unavoidable.
172Future versions may eliminate one or both of these
173semantic guarantees in order to fix the bug.
|