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