1 files changed, 178 insertions, 0 deletions
diff --git a/src/lib/libc/stdlib/getenv.3 b/src/lib/libc/stdlib/getenv.3
new file mode 100644
index 0000000000..c24e480ffb
--- /dev/null
+++ b/src/lib/libc/stdlib/getenv.3
@@ -0,0 +1,178 @@
+.\" Copyright (c) 1988, 1991, 1993
+.\"    The Regents of the University of California.  All rights reserved.
+.\"
+.\" This code is derived from software contributed to Berkeley by
+.\" the American National Standards Committee X3, on Information
+.\" Processing Systems.
+.\"
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\" 1. Redistributions of source code must retain the above copyright
+.\"    notice, this list of conditions and the following disclaimer.
+.\" 2. Redistributions in binary form must reproduce the above copyright
+.\"    notice, this list of conditions and the following disclaimer in the
+.\"    documentation and/or other materials provided with the distribution.
+.\" 3. Neither the name of the University nor the names of its contributors
+.\"    may be used to endorse or promote products derived from this software
+.\"    without specific prior written permission.
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
+.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
+.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
+.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
+.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
+.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
+.\" SUCH DAMAGE.
+.\"
+.\"     $OpenBSD: getenv.3,v 1.15 2010/07/06 20:52:00 naddy Exp $
+.\"
+.Dd $Mdocdate: July 6 2010 $
+.Dt GETENV 3
+.Os
+.Sh NAME
+.Nm getenv ,
+.Nm putenv ,
+.Nm setenv ,
+.Nm unsetenv
+.Nd environment variable functions
+.Sh SYNOPSIS
+.Fd #include <stdlib.h>
+.Ft char *
+.Fn getenv "const char *name"
+.Ft int
+.Fn setenv "const char *name" "const char *value" "int overwrite"
+.Ft int
+.Fn putenv "char *string"
+.Ft int
+.Fn unsetenv "const char *name"
+.Sh DESCRIPTION
+These functions set, unset, and fetch environment variables from the host
+.Em environment list .
+For compatibility with differing environment conventions, the given arguments
+.Fa name
+and
+.Fa value
+may be appended and prepended, respectively, with an equal sign
+.Dq Li \&= .
+.Pp
+The
+.Fn getenv
+function obtains the current value of the environment variable
+.Fa name .
+If the variable
+.Fa name
+is not in the current environment, a null pointer is returned.
+.Pp
+The
+.Fn setenv
+function inserts or resets the environment variable
+.Fa name
+in the current environment list.
+If the variable
+.Fa name
+does not exist in the list, it is inserted with the given
+.Fa value .
+If the variable does exist, the argument
+.Fa overwrite
+is tested; if
+.Fa overwrite
+is zero, the variable is not reset, otherwise it is reset to the given
+.Fa value .
+.Pp
+The
+.Fn putenv
+function takes an argument of the form
+.Ar name Ns = Ns Ar value .
+The memory pointed to by
+.Ar string
+becomes part of the environment and must not be deallocated by the caller.
+If the variable already exists, it will be overwritten.
+A common source of bugs is to pass a
+.Ar string
+argument that is a locally scoped string buffer.
+This will result in corruption of the environment after leaving
+the scope in which the variable is defined.
+For this reason, the
+.Fn setenv
+function is preferred over
+.Fn putenv .
+.Pp
+The
+.Fn unsetenv
+function deletes all instances of the variable name pointed to by
+.Fa name
+from the list.
+.Sh RETURN VALUES
+These functions
+return zero if successful; otherwise the global variable
+.Va errno
+is set to indicate the error and \-1 is returned.
+.Pp
+If
+.Fn getenv
+is successful, the string returned should be considered read-only.
+.Sh ERRORS
+.Bl -tag -width Er
+.It Bq Er EINVAL
+The
+.Fn setenv
+or
+.Fn unsetenv
+function was passed a
+.Ar name
+containing an
+.Sq =
+character.
+.Pp
+The
+.Fn unsetenv
+function was passed an empty
+.Ar name
+or a NULL pointer.
+.Pp
+The
+.Fn putenv
+function was passed a
+.Ar string
+that did not contain an
+.Sq =
+character.
+.It Bq Er ENOMEM
+The
+.Fn setenv
+or
+.Fn putenv
+function failed because it was unable to allocate memory for the environment.
+.El
+.Sh SEE ALSO
+.Xr csh 1 ,
+.Xr sh 1 ,
+.Xr execve 2 ,
+.Xr environ 7
+.Sh STANDARDS
+The
+.Fn getenv
+function conforms to
+.St -ansiC .
+.Sh HISTORY
+The function
+.Fn getenv
+appeared in
+.At v7
+and
+.Bx 3 .
+The functions
+.Fn setenv
+and
+.Fn unsetenv
+appeared in
+.Bx 4.3 Tahoe .
+The
+.Fn putenv
+function appeared in
+.Bx 4.3 Reno .

diff --git a/src/lib/libc/stdlib/getenv.3 b/src/lib/libc/stdlib/getenv.3 new file mode 100644 index 0000000000..c24e480ffb --- /dev/null +++ b/src/lib/libc/stdlib/getenv.3
@@ -0,0 +1,178 @@
	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.15 2010/07/06 20:52:00 naddy Exp $
	33	.\"
	34	.Dd $Mdocdate: July 6 2010 $
	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	.Fd #include <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
	54	These functions set, unset, and fetch environment variables from the host
	55	.Em environment list .
	56	For compatibility with differing environment conventions, the given arguments
	57	.Fa name
	58	and
	59	.Fa value
	60	may be appended and prepended, respectively, with an equal sign
	61	.Dq Li \&= .
	62	.Pp
	63	The
	64	.Fn getenv
	65	function obtains the current value of the environment variable
	66	.Fa name .
	67	If the variable
	68	.Fa name
	69	is not in the current environment, a null pointer is returned.
	70	.Pp
	71	The
	72	.Fn setenv
	73	function inserts or resets the environment variable
	74	.Fa name
	75	in the current environment list.
	76	If the variable
	77	.Fa name
	78	does not exist in the list, it is inserted with the given
	79	.Fa value .
	80	If the variable does exist, the argument
	81	.Fa overwrite
	82	is tested; if
	83	.Fa overwrite
	84	is zero, the variable is not reset, otherwise it is reset to the given
	85	.Fa value .
	86	.Pp
	87	The
	88	.Fn putenv
	89	function takes an argument of the form
	90	.Ar name Ns = Ns Ar value .
	91	The memory pointed to by
	92	.Ar string
	93	becomes part of the environment and must not be deallocated by the caller.
	94	If the variable already exists, it will be overwritten.
	95	A common source of bugs is to pass a
	96	.Ar string
	97	argument that is a locally scoped string buffer.
	98	This will result in corruption of the environment after leaving
	99	the scope in which the variable is defined.
	100	For this reason, the
	101	.Fn setenv
	102	function is preferred over
	103	.Fn putenv .
	104	.Pp
	105	The
	106	.Fn unsetenv
	107	function deletes all instances of the variable name pointed to by
	108	.Fa name
	109	from the list.
	110	.Sh RETURN VALUES
	111	These functions
	112	return zero if successful; otherwise the global variable
	113	.Va errno
	114	is set to indicate the error and \-1 is returned.
	115	.Pp
	116	If
	117	.Fn getenv
	118	is successful, the string returned should be considered read-only.
	119	.Sh ERRORS
	120	.Bl -tag -width Er
	121	.It Bq Er EINVAL
	122	The
	123	.Fn setenv
	124	or
	125	.Fn unsetenv
	126	function was passed a
	127	.Ar name
	128	containing an
	129	.Sq =
	130	character.
	131	.Pp
	132	The
	133	.Fn unsetenv
	134	function was passed an empty
	135	.Ar name
	136	or a NULL pointer.
	137	.Pp
	138	The
	139	.Fn putenv
	140	function was passed a
	141	.Ar string
	142	that did not contain an
	143	.Sq =
	144	character.
	145	.It Bq Er ENOMEM
	146	The
	147	.Fn setenv
	148	or
	149	.Fn putenv
	150	function failed because it was unable to allocate memory for the environment.
	151	.El
	152	.Sh SEE ALSO
	153	.Xr csh 1 ,
	154	.Xr sh 1 ,
	155	.Xr execve 2 ,
	156	.Xr environ 7
	157	.Sh STANDARDS
	158	The
	159	.Fn getenv
	160	function conforms to
	161	.St -ansiC .
	162	.Sh HISTORY
	163	The function
	164	.Fn getenv
	165	appeared in
	166	.At v7
	167	and
	168	.Bx 3 .
	169	The functions
	170	.Fn setenv
	171	and
	172	.Fn unsetenv
	173	appeared in
	174	.Bx 4.3 Tahoe .
	175	The
	176	.Fn putenv
	177	function appeared in
	178	.Bx 4.3 Reno .