Reduce lock contention for simple cases in stdtime.
[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.
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: src/lib/libc/stdlib/getenv.3,v 1.4.2.7 2001/12/14 18:33:58 ru Exp $
0b84df5c 38.\" $DragonFly: src/lib/libc/stdlib/getenv.3,v 1.5 2006/02/17 19:35:06 swildner Exp $
984263bc
MD
39.\"
40.Dd December 11, 1993
41.Dt GETENV 3
42.Os
43.Sh NAME
44.Nm getenv ,
45.Nm putenv ,
46.Nm setenv ,
47.Nm unsetenv
48.Nd environment variable functions
49.Sh LIBRARY
50.Lb libc
51.Sh SYNOPSIS
52.In stdlib.h
53.Ft char *
54.Fn getenv "const char *name"
55.Ft int
56.Fn setenv "const char *name" "const char *value" "int overwrite"
57.Ft int
58.Fn putenv "const char *string"
59.Ft void
60.Fn unsetenv "const char *name"
61.Sh DESCRIPTION
62These functions set, unset and fetch environment variables from the
63host
64.Em environment list .
65For compatibility with differing environment conventions,
66the given arguments
67.Ar name
68and
69.Ar value
70may be appended and prepended,
71respectively,
72with an equal sign
73.Dq Li \&= .
74.Pp
75The
76.Fn getenv
77function obtains the current value of the environment variable,
78.Ar name .
79If the variable
80.Ar name
81is not in the current environment,
82a null pointer is returned.
83.Pp
84The
85.Fn setenv
86function inserts or resets the environment variable
87.Ar name
88in the current environment list.
89If the variable
90.Ar name
91does not exist in the list,
92it is inserted with the given
93.Ar value .
94If the variable does exist, the argument
95.Ar overwrite
96is tested; if
97.Ar overwrite is
98zero, the
99variable is not reset, otherwise it is reset
100to the given
101.Ar value .
102.Pp
103The
104.Fn putenv
105function takes an argument of the form ``name=value'' and is
106equivalent to:
107.Bd -literal -offset indent
108setenv(name, value, 1);
109.Ed
110.Pp
111The
112.Fn unsetenv
113function
114deletes all instances of the variable name pointed to by
115.Fa name
116from the list.
117.Sh RETURN VALUES
118.Rv -std setenv putenv
abf9e20c
JR
119.Pp
120The
121.Fn getenv
122function returns NULL if the environment variable was not found.
123If the variable was found,
124it returns the value of the variable as a NULL terminated string.
125This string should not be modified or freed.
984263bc
MD
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 .
0b84df5c
SW
145.Sh HISTORY
146The functions
147.Fn setenv
148and
149.Fn unsetenv
150appeared in
151.At v7 .
152The
153.Fn putenv
154function appeared in
155.Bx 4.3 Reno .
984263bc
MD
156.Sh BUGS
157Successive calls to
158.Fn setenv
159or
160.Fn putenv
161assigning a differently sized
162.Ar value
163to the same
164.Ar name
165will result in a memory leak. The
9bb2a92d 166.Dx
984263bc
MD
167semantics for these functions
168(namely, that the contents of
169.Ar value
170are copied and that old values remain accessible indefinitely) make this
171bug unavoidable. Future versions may eliminate one or both of these
172semantic guarantees in order to fix the bug.