lib/dlfcn: whitespace cleanup, remove unnecessary prototype
[dragonfly.git] / lib / libc / stdlib / getenv.3
CommitLineData
984263bc
MD
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.
dc71b7ab 16.\" 3. Neither the name of the University nor the names of its contributors
984263bc
MD
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
5d0641a4 33.\" $FreeBSD: src/lib/libc/stdlib/getenv.3,v 1.27 2007/07/04 00:00:39 scf Exp $
0b84df5c 34.\" $DragonFly: src/lib/libc/stdlib/getenv.3,v 1.5 2006/02/17 19:35:06 swildner Exp $
984263bc 35.\"
5d0641a4 36.Dd June 20, 2007
984263bc
MD
37.Dt GETENV 3
38.Os
39.Sh NAME
40.Nm getenv ,
41.Nm putenv ,
42.Nm setenv ,
43.Nm unsetenv
44.Nd environment variable functions
45.Sh LIBRARY
46.Lb libc
47.Sh SYNOPSIS
48.In stdlib.h
49.Ft char *
50.Fn getenv "const char *name"
51.Ft int
52.Fn setenv "const char *name" "const char *value" "int overwrite"
53.Ft int
5d0641a4
PA
54.Fn putenv "char *string"
55.Ft int
984263bc
MD
56.Fn unsetenv "const char *name"
57.Sh DESCRIPTION
58These functions set, unset and fetch environment variables from the
59host
60.Em environment list .
984263bc
MD
61.Pp
62The
63.Fn getenv
64function obtains the current value of the environment variable,
5d0641a4
PA
65.Fa name .
66The application should not modify the string pointed
67to by the
68.Fn getenv
69function.
984263bc
MD
70.Pp
71The
72.Fn setenv
73function inserts or resets the environment variable
5d0641a4 74.Fa name
984263bc
MD
75in the current environment list.
76If the variable
5d0641a4 77.Fa name
984263bc
MD
78does not exist in the list,
79it is inserted with the given
5d0641a4 80.Fa value .
984263bc 81If the variable does exist, the argument
5d0641a4 82.Fa overwrite
984263bc 83is tested; if
5d0641a4
PA
84.Fa overwrite
85is zero, the
984263bc
MD
86variable is not reset, otherwise it is reset
87to the given
5d0641a4 88.Fa value .
984263bc
MD
89.Pp
90The
91.Fn putenv
5d0641a4
PA
92function takes an argument of the form ``name=value'' and
93puts it directly into the current environment,
94so altering the argument shall change the environment.
95If the variable
96.Fa name
97does not exist in the list,
98it is inserted with the given
99.Fa value .
100If the variable
101.Fa name
102does exist, it is reset to the given
103.Fa value .
984263bc
MD
104.Pp
105The
106.Fn unsetenv
107function
108deletes all instances of the variable name pointed to by
109.Fa name
110from the list.
111.Sh RETURN VALUES
abf9e20c
JR
112The
113.Fn getenv
5d0641a4
PA
114function returns the value of the environment variable as a
115.Dv NUL Ns
116-terminated string.
117If the variable
118.Fa name
119is not in the current environment,
120.Dv NULL
121is returned.
122.Pp
123.Rv -std setenv putenv unsetenv
984263bc
MD
124.Sh ERRORS
125.Bl -tag -width Er
5d0641a4 126.It Bq Er EINVAL
984263bc 127The function
5d0641a4 128.Fn getenv ,
984263bc
MD
129.Fn setenv
130or
5d0641a4
PA
131.Fn unsetenv
132failed because the
133.Fa name
134is a
135.Dv NULL
136pointer, points to an empty string, or points to a string containing an
137.Dq Li \&=
138character.
139.Pp
140The function
141.Fn putenv
142failed because
143.Fa string
144is a
145.Dv NULL
146pointer,
147.Fa string is without an
148.Dq Li \&=
149character or
150.Dq Li \&=
151is the first character in
152.Fa string .
153This does not follow the
154.Tn POSIX
155specification.
156.It Bq Er ENOMEM
157The function
158.Fn setenv ,
159.Fn unsetenv
160or
984263bc
MD
161.Fn putenv
162failed because they were unable to allocate memory for the environment.
5d0641a4
PA
163.It Bq Er EFAULT
164The functions
165.Fn setenv ,
166.Fn unsetenv
167or
168.Fn putenv
169failed to make a valid copy of the environment due to the environment being
170corrupt (i.e., a name without a value). A warning will be output to stderr with
171information about the issue.
984263bc
MD
172.El
173.Sh SEE ALSO
174.Xr csh 1 ,
175.Xr sh 1 ,
176.Xr execve 2 ,
177.Xr environ 7
178.Sh STANDARDS
179The
180.Fn getenv
181function conforms to
182.St -isoC .
5d0641a4
PA
183The
184.Fn setenv ,
185.Fn putenv
186and
187.Fn unsetenv
188functions conforms to
189.St -p1003.1-2001 .
0b84df5c
SW
190.Sh HISTORY
191The functions
192.Fn setenv
193and
194.Fn unsetenv
195appeared in
196.At v7 .
197The
198.Fn putenv
199function appeared in
200.Bx 4.3 Reno .
5d0641a4
PA
201.Pp
202Until
203.Fx 7.0 ,
204.Fn putenv
205would make a copy of
206.Fa string
207and insert it into the environment using
208.Fn setenv .
209This was changed to use
210.Fa string
211as the memory location of the ``name=value'' pair to follow the
212.Tn POSIX
213specification.
984263bc
MD
214.Sh BUGS
215Successive calls to
216.Fn setenv
5d0641a4
PA
217that assign a larger-sized
218.Fa value
219than any previous value to the same
220.Fa name
221will result in a memory leak.
222The
9bb2a92d 223.Dx
5d0641a4 224semantics for this function
984263bc 225(namely, that the contents of
5d0641a4 226.Fa value
984263bc 227are copied and that old values remain accessible indefinitely) make this
5d0641a4
PA
228bug unavoidable.
229Future versions may eliminate one or both of these
984263bc 230semantic guarantees in order to fix the bug.