getenv.3 (ba174a5e38b1ab764c4a36ef4dd83e80c4add148) getenv.3 (2966d28c322dcfa4b9db2558da0b91839e7798b9)
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

--- 18 unchanged lines hidden (view full) ---

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$
34.\"
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

--- 18 unchanged lines hidden (view full) ---

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$
34.\"
35.Dd October 12, 2006
35.Dd June 20, 2007
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 "const char *string"
54.Ft void
53.Fn putenv "char *string"
54.Ft int
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 \&= .
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

--- 15 unchanged lines hidden (view full) ---

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
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

--- 15 unchanged lines hidden (view full) ---

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
100function takes an argument of the form ``name=value'' and is
101equivalent to:
102.Bd -literal -offset indent
103setenv(name, value, 1);
104.Ed
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 .
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
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
124.Rv -std setenv putenv
122.Rv -std setenv putenv unsetenv
125.Sh ERRORS
126.Bl -tag -width Er
123.Sh ERRORS
124.Bl -tag -width Er
127.It Bq Er ENOMEM
125.It Bq Er EINVAL
128The function
126The function
127.Fn getenv ,
129.Fn setenv
130or
128.Fn setenv
129or
130.Fn unsetenv
131failed because the
132.Fa name
133is a
134.Dv NULL
135pointer, points to an empty string, or points to a string containing an
136.Dq Li \&=
137character.
138.Pp
139The function
131.Fn putenv
140.Fn putenv
141failed because
142.Fa string
143is a
144.Dv NULL
145pointer,
146.Fa string is without an
147.Dq Li \&=
148character or
149.Dq Li \&=
150is the first character in
151.Fa string .
152This does not follow the
153.Tn POSIX
154specification.
155.It Bq Er ENOMEM
156The function
157.Fn setenv ,
158.Fn unsetenv
159or
160.Fn putenv
132failed because they were unable to allocate memory for the environment.
161failed because they were unable to allocate memory for the environment.
162.It Bq Er EFAULT
163The functions
164.Fn setenv ,
165.Fn unsetenv
166or
167.Fn putenv
168failed to make a valid copy of the environment due to the environment being
169corrupt (i.e., a name without a value). A warning will be output to stderr with
170information about the issue.
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 .
171.El
172.Sh SEE ALSO
173.Xr csh 1 ,
174.Xr sh 1 ,
175.Xr execve 2 ,
176.Xr environ 7
177.Sh STANDARDS
178The
179.Fn getenv
180function conforms to
181.St -isoC .
182The
183.Fn setenv ,
184.Fn putenv
185and
186.Fn unsetenv
187functions conforms to
188.St -p1003.1-2001 .
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 .
189.Sh HISTORY
190The functions
191.Fn setenv
192and
193.Fn unsetenv
194appeared in
195.At v7 .
196The
197.Fn putenv
198function appeared in
199.Bx 4.3 Reno .
200.Pp
201Until
202.Fx 7.0 ,
203.Fn putenv
204would make a copy of
205.Fa string
206and insert it into the environment using
207.Fn setenv .
208This was changed to use
209.Fa string
210as the memory location of the ``name=value'' pair to follow the
211.Tn POSIX
212specification.
155.Sh BUGS
156Successive calls to
157.Fn setenv
213.Sh BUGS
214Successive calls to
215.Fn setenv
158or
159.Fn putenv
160assigning a differently sized
216that assign a larger-sized
161.Fa value
217.Fa value
162to the same
218than any previous value to the same
163.Fa name
164will result in a memory leak.
165The
166.Fx
219.Fa name
220will result in a memory leak.
221The
222.Fx
167semantics for these functions
223semantics for this function
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.
224(namely, that the contents of
225.Fa value
226are copied and that old values remain accessible indefinitely) make this
227bug unavoidable.
228Future versions may eliminate one or both of these
229semantic guarantees in order to fix the bug.