]> git.saurik.com Git - apple/libc.git/blame_incremental - stdlib/FreeBSD/getenv.3
Libc-1244.50.9.tar.gz
[apple/libc.git] / stdlib / FreeBSD / getenv.3
... / ...
CommitLineData
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. 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$
34.\"
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
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 .
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
91function takes an argument of the form ``name=value'' and is
92equivalent to:
93.Bd -literal -offset indent
94setenv(name, value, 1);
95.Ed
96.Pp
97The string pointed to by
98.Fa string
99becomes part of the environment.
100A program should not alter or free the string,
101and should not use stack or other transient string variables
102as arguments to
103.Fn putenv .
104The
105.Fn setenv
106function is strongly preferred to
107.Fn putenv .
108.Pp
109The
110.Fn unsetenv
111function
112deletes all instances of the variable name pointed to by
113.Fa name
114from the list.
115Note that only the variable name (e.g., "NAME") should be given;
116"NAME=value" will not work.
117.Sh RETURN VALUES
118The
119.Fn getenv
120function returns the value of the environment variable as a
121.Dv NUL Ns
122-terminated string.
123If the variable
124.Fa name
125is not in the current environment,
126.Dv NULL
127is returned.
128.Pp
129.Rv -std setenv putenv unsetenv
130.Sh ERRORS
131.Bl -tag -width Er
132.It Bq Er EINVAL
133The function
134.Fn getenv ,
135.Fn setenv
136or
137.Fn unsetenv
138failed because the
139.Fa name
140is a
141.Dv NULL
142pointer, points to an empty string, or points to a string containing an
143.Dq Li \&=
144character.
145.Pp
146The function
147.Fn putenv
148failed because
149.Fa string
150is a
151.Dv NULL
152pointer or
153.Fa string
154is without an
155.Dq Li \&=
156character.
157.It Bq Er ENOMEM
158The function
159.Fn setenv ,
160.Fn unsetenv
161or
162.Fn putenv
163failed because it was unable to allocate memory for the environment.
164.El
165.Sh LEGACY SYNOPSIS
166.Fd #include <stdlib.h>
167.Pp
168.Ft void
169.br
170.Fo unsetenv
171.Fa "const char *name"
172.Fc ;
173.Pp
174.Fn unsetenv
175doesn't return a value.
176.Sh COMPATIBILITY
177.Fn putenv
178no longer copies its input buffer.
179This often appears in crash logs as a crash in
180.Fn getenv .
181Avoid passing local buffers or freeing the memory
182that is passed to
183.Fn putenv .
184Use
185.Fn setenv ,
186which still makes an internal copy of its buffers.
187.Pp
188.Fn unsetenv
189no longer parses the variable name;
190e.g., unsetenv ("FOO=BAR") no longer works.
191Use unsetenv("FOO").
192.Fn unsetenv
193also now returns a status value and will set
194.Va errno
195to EINVAL if
196.Fa name
197is not a defined environment variable.
198.Sh SEE ALSO
199.Xr csh 1 ,
200.Xr sh 1 ,
201.Xr execve 2 ,
202.Xr compat 5 ,
203.Xr environ 7
204.Sh STANDARDS
205The
206.Fn getenv
207function conforms to
208.St -isoC .
209The
210.Fn setenv ,
211.Fn putenv
212and
213.Fn unsetenv
214functions conforms to
215.St -p1003.1-2001 .
216.Sh HISTORY
217The functions
218.Fn setenv
219and
220.Fn unsetenv
221appeared in
222.At v7 .
223The
224.Fn putenv
225function appeared in
226.Bx 4.3 Reno .
227.Sh BUGS
228Successive calls to
229.Fn setenv
230that assign a larger-sized
231.Fa value
232than any previous value to the same
233.Fa name
234will result in a memory leak.
235The
236.Fx
237semantics for this function
238(namely, that the contents of
239.Fa value
240are copied and that old values remain accessible indefinitely) make this
241bug unavoidable.
242Future versions may eliminate one or both of these
243semantic guarantees in order to fix the bug.