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.\" 3. All advertising materials mentioning features or use of this software
17.\" must display the following acknowledgement:
18.\" This product includes software developed by the University of
19.\" California, Berkeley and its contributors.
20.\" 4. Neither the name of the University nor the names of its contributors
21.\" may be used to endorse or promote products derived from this software
22.\" without specific prior written permission.
23.\"
24.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
25.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
26.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
27.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
28.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
29.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
30.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
31.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
32.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
33.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
34.\" SUCH DAMAGE.
35.\"
36.\" @(#)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.\" 3. All advertising materials mentioning features or use of this software
17.\" must display the following acknowledgement:
18.\" This product includes software developed by the University of
19.\" California, Berkeley and its contributors.
20.\" 4. Neither the name of the University nor the names of its contributors
21.\" may be used to endorse or promote products derived from this software
22.\" without specific prior written permission.
23.\"
24.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
25.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
26.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
27.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
28.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
29.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
30.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
31.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
32.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
33.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
34.\" SUCH DAMAGE.
35.\"
36.\" @(#)getenv.3 8.2 (Berkeley) 12/11/93
|
37.\" $FreeBSD: head/lib/libc/stdlib/getenv.3 131728 2004-07-06 23:21:36Z hmp $
| 37.\" $FreeBSD: head/lib/libc/stdlib/getenv.3 131754 2004-07-07 19:57:16Z ru $
|
38.\"
39.Dd December 11, 1993
40.Dt GETENV 3
41.Os
42.Sh NAME
43.Nm getenv ,
44.Nm putenv ,
45.Nm setenv ,
46.Nm unsetenv
47.Nd environment variable functions
48.Sh LIBRARY
49.Lb libc
50.Sh SYNOPSIS
51.In stdlib.h
52.Ft char *
53.Fn getenv "const char *name"
54.Ft int
55.Fn setenv "const char *name" "const char *value" "int overwrite"
56.Ft int
57.Fn putenv "const char *string"
58.Ft void
59.Fn unsetenv "const char *name"
60.Sh DESCRIPTION
61These functions set, unset and fetch environment variables from the
62host
63.Em environment list .
64For compatibility with differing environment conventions,
65the given arguments
66.Fa name
67and
68.Fa value
69may be appended and prepended,
70respectively,
71with an equal sign
72.Dq Li \&= .
73.Pp
74The
75.Fn getenv
76function obtains the current value of the environment variable,
77.Fa name .
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
94zero, the
95variable is not reset, otherwise it is reset
96to the given
97.Fa value .
98.Pp
99The
100.Fn putenv
101function takes an argument of the form ``name=value'' and is
102equivalent to:
103.Bd -literal -offset indent
104setenv(name, value, 1);
105.Ed
106.Pp
107The
108.Fn unsetenv
109function
110deletes all instances of the variable name pointed to by
111.Fa name
112from the list.
113.Sh RETURN VALUES
114The
115.Fn getenv
| 38.\"
39.Dd December 11, 1993
40.Dt GETENV 3
41.Os
42.Sh NAME
43.Nm getenv ,
44.Nm putenv ,
45.Nm setenv ,
46.Nm unsetenv
47.Nd environment variable functions
48.Sh LIBRARY
49.Lb libc
50.Sh SYNOPSIS
51.In stdlib.h
52.Ft char *
53.Fn getenv "const char *name"
54.Ft int
55.Fn setenv "const char *name" "const char *value" "int overwrite"
56.Ft int
57.Fn putenv "const char *string"
58.Ft void
59.Fn unsetenv "const char *name"
60.Sh DESCRIPTION
61These functions set, unset and fetch environment variables from the
62host
63.Em environment list .
64For compatibility with differing environment conventions,
65the given arguments
66.Fa name
67and
68.Fa value
69may be appended and prepended,
70respectively,
71with an equal sign
72.Dq Li \&= .
73.Pp
74The
75.Fn getenv
76function obtains the current value of the environment variable,
77.Fa name .
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
94zero, the
95variable is not reset, otherwise it is reset
96to the given
97.Fa value .
98.Pp
99The
100.Fn putenv
101function takes an argument of the form ``name=value'' and is
102equivalent to:
103.Bd -literal -offset indent
104setenv(name, value, 1);
105.Ed
106.Pp
107The
108.Fn unsetenv
109function
110deletes all instances of the variable name pointed to by
111.Fa name
112from the list.
113.Sh RETURN VALUES
114The
115.Fn getenv
|
116function returns the value of the environment variable as a nul terminated
117string.
| 116function returns the value of the environment variable as a
117.Dv NUL Ns
118-terminated string.
|
118If the variable
119.Fa name
120is not in the current environment,
121.Dv NULL
122is returned.
123.Pp
124.Rv -std setenv putenv
125.Sh ERRORS
126.Bl -tag -width Er
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 .
144.Sh BUGS
145Successive calls to
146.Fn setenv
147or
148.Fn putenv
149assigning a differently sized
150.Fa value
151to the same
152.Fa name
153will result in a memory leak.
154The
155.Fx
156semantics for these functions
157(namely, that the contents of
158.Fa value
159are copied and that old values remain accessible indefinitely) make this
160bug unavoidable.
161Future versions may eliminate one or both of these
162semantic guarantees in order to fix the bug.
163.Sh HISTORY
164The functions
165.Fn setenv
166and
167.Fn unsetenv
168appeared in
169.At v7 .
170The
171.Fn putenv
172function appeared in
173.Bx 4.3 Reno .
| 119If the variable
120.Fa name
121is not in the current environment,
122.Dv NULL
123is returned.
124.Pp
125.Rv -std setenv putenv
126.Sh ERRORS
127.Bl -tag -width Er
128.It Bq Er ENOMEM
129The function
130.Fn setenv
131or
132.Fn putenv
133failed because they were unable to allocate memory for the environment.
134.El
135.Sh SEE ALSO
136.Xr csh 1 ,
137.Xr sh 1 ,
138.Xr execve 2 ,
139.Xr environ 7
140.Sh STANDARDS
141The
142.Fn getenv
143function conforms to
144.St -isoC .
145.Sh BUGS
146Successive calls to
147.Fn setenv
148or
149.Fn putenv
150assigning a differently sized
151.Fa value
152to the same
153.Fa name
154will result in a memory leak.
155The
156.Fx
157semantics for these functions
158(namely, that the contents of
159.Fa value
160are copied and that old values remain accessible indefinitely) make this
161bug unavoidable.
162Future versions may eliminate one or both of these
163semantic guarantees in order to fix the bug.
164.Sh HISTORY
165The functions
166.Fn setenv
167and
168.Fn unsetenv
169appeared in
170.At v7 .
171The
172.Fn putenv
173function appeared in
174.Bx 4.3 Reno .
|