summaryrefslogtreecommitdiff
path: root/src/lib/libc/stdlib/getenv.3
diff options
context:
space:
mode:
Diffstat (limited to 'src/lib/libc/stdlib/getenv.3')
-rw-r--r--src/lib/libc/stdlib/getenv.3191
1 files changed, 0 insertions, 191 deletions
diff --git a/src/lib/libc/stdlib/getenv.3 b/src/lib/libc/stdlib/getenv.3
deleted file mode 100644
index 5a219a5c03..0000000000
--- a/src/lib/libc/stdlib/getenv.3
+++ /dev/null
@@ -1,191 +0,0 @@
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.\" $OpenBSD: getenv.3,v 1.23 2022/08/08 22:40:03 millert Exp $
33.\"
34.Dd $Mdocdate: August 8 2022 $
35.Dt GETENV 3
36.Os
37.Sh NAME
38.Nm getenv ,
39.Nm putenv ,
40.Nm setenv ,
41.Nm unsetenv
42.Nd environment variable functions
43.Sh SYNOPSIS
44.In stdlib.h
45.Ft char *
46.Fn getenv "const char *name"
47.Ft int
48.Fn setenv "const char *name" "const char *value" "int overwrite"
49.Ft int
50.Fn putenv "char *string"
51.Ft int
52.Fn unsetenv "const char *name"
53.Sh DESCRIPTION
54These functions set, unset, and fetch environment variables from the host
55.Em environment list .
56.Pp
57The
58.Fn getenv
59function obtains the current value of the environment variable
60.Fa name .
61If the variable
62.Fa name
63is not in the current environment, a null pointer is returned.
64.Pp
65The
66.Fn setenv
67function inserts or resets the environment variable
68.Fa name
69in the current environment list.
70If the variable
71.Fa name
72does not exist in the list, it is inserted with the given
73.Fa value .
74If the variable does exist, the argument
75.Fa overwrite
76is tested; if
77.Fa overwrite
78is zero, the variable is not reset, otherwise it is reset to the given
79.Fa value .
80.Pp
81The
82.Fn putenv
83function takes an argument of the form
84.Ar name Ns = Ns Ar value .
85The memory pointed to by
86.Ar string
87becomes part of the environment and must not be deallocated by the caller.
88If the variable already exists, it will be overwritten.
89A common source of bugs is to pass a
90.Ar string
91argument that is a locally scoped string buffer.
92This will result in corruption of the environment after leaving
93the scope in which the variable is defined.
94For this reason, the
95.Fn setenv
96function is preferred over
97.Fn putenv .
98.Pp
99The
100.Fn unsetenv
101function deletes all instances of the variable name pointed to by
102.Fa name
103from the list.
104.Sh RETURN VALUES
105.Rv -std putenv setenv unsetenv
106.Pp
107The
108.Fn getenv
109function returns a pointer to the requested value, or
110.Dv NULL
111if it could not be found.
112If
113.Fn getenv
114is successful, the string returned should be considered read-only.
115.Sh ERRORS
116.Bl -tag -width Er
117.It Bq Er EINVAL
118The
119.Fn setenv
120or
121.Fn unsetenv
122function was passed an empty
123.Ar name
124or a NULL pointer, or was passed a
125.Ar name
126containing an
127.Sq =
128character.
129.Pp
130The
131.Fn putenv
132function was passed a
133.Ar string
134that did not contain an
135.Sq =
136character, or was passed a
137.Ar string
138that started with the
139.Sq =
140character.
141.It Bq Er ENOMEM
142The
143.Fn setenv
144or
145.Fn putenv
146function failed because it was unable to allocate memory for the environment.
147.El
148.Sh SEE ALSO
149.Xr csh 1 ,
150.Xr sh 1 ,
151.Xr execve 2 ,
152.Xr issetugid 2 ,
153.Xr environ 7
154.Sh STANDARDS
155The
156.Fn getenv
157function conforms to
158.St -ansiC .
159The
160.Fn putenv ,
161.Fn setenv ,
162and
163.Fn unsetenv
164functions conform to
165.St -p1003.1-2008 .
166.Sh HISTORY
167The function
168.Fn getenv
169appeared in
170.At v7
171and
172.Bx 3 .
173The functions
174.Fn setenv
175and
176.Fn unsetenv
177appeared in
178.Bx 4.3 Tahoe .
179The
180.Fn putenv
181function first appeared in
182.At V.2
183and was reimplemented for
184.Bx 4.3 Reno .
185.Sh CAVEATS
186Library code must be careful about using
187.Fn getenv
188to read untrusted environment variables in setuid programs.
189The
190.Fn issetugid
191function is provided for this purpose.
generated by cgit v1.2.3-55-g6feb (git 2.39.1) at 2025-04-26 17:59:29 +0000