Libc-1439.100.3.tar.gz

[apple/libc.git] / stdlib / FreeBSD / getenv.3

diff --git a/stdlib/FreeBSD/getenv.3 b/stdlib/FreeBSD/getenv.3
index fc1963287a5ed7f38c7034aaa419bf876eb92a0d..ebe5d2850e5bb979d6b7eb93f7837e62c4a7d461 100644 (file)
--- a/stdlib/FreeBSD/getenv.3
+++ b/stdlib/FreeBSD/getenv.3
@@ -13,11 +13,7 @@
 .\" 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.
 .\" 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. All advertising materials mentioning features or use of this software
-.\"    must display the following acknowledgement:
-.\"    This product includes software developed by the University of
-.\"    California, Berkeley and its contributors.
-.\" 4. Neither the name of the University nor the names of its contributors
+.\" 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.
 .\"
 .\"    may be used to endorse or promote products derived from this software
 .\"    without specific prior written permission.
 .\"


@@ -34,9 +30,9 @@
 .\" SUCH DAMAGE.
 .\"
 .\"     @(#)getenv.3   8.2 (Berkeley) 12/11/93
 .\" SUCH DAMAGE.
 .\"
 .\"     @(#)getenv.3   8.2 (Berkeley) 12/11/93

-.\" $FreeBSD: src/lib/libc/stdlib/getenv.3,v 1.16 2004/07/07 19:57:13 ru Exp $
+.\" $FreeBSD$

 .\"
 .\"

-.Dd December 11, 1993
+.Dd June 20, 2007

 .Dt GETENV 3
 .Os
 .Sh NAME
 .Dt GETENV 3
 .Os
 .Sh NAME


@@ -54,27 +50,22 @@
 .Ft int
 .Fn setenv "const char *name" "const char *value" "int overwrite"
 .Ft int
 .Ft int
 .Fn setenv "const char *name" "const char *value" "int overwrite"
 .Ft int

-.Fn putenv "const char *string"
-.Ft void
+.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 .
 .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 .
 .Pp
 The
 .Fn getenv
 function obtains the current value of the environment variable,
 .Fa name .

+The application should not modify the string pointed
+to by the
+.Fn getenv
+function.

 .Pp
 The
 .Fn setenv
 .Pp
 The
 .Fn setenv


@@ -90,8 +81,7 @@ If the variable does exist, the argument
 .Fa overwrite
 is tested; if
 .Fa overwrite
 .Fa overwrite
 is tested; if
 .Fa overwrite

-is
-zero, the
+is zero, the

 variable is not reset, otherwise it is reset
 to the given
 .Fa value .
 variable is not reset, otherwise it is reset
 to the given
 .Fa value .


@@ -104,12 +94,26 @@ equivalent to:
 setenv(name, value, 1);
 .Ed
 .Pp
 setenv(name, value, 1);
 .Ed
 .Pp

+The string pointed to by
+.Fa string
+becomes part of the environment.
+A program should not alter or free the string,
+and should not use stack or other transient string variables
+as arguments to
+.Fn putenv .
+The
+.Fn setenv
+function is strongly preferred to
+.Fn putenv .
+.Pp

 The
 .Fn unsetenv
 function
 deletes all instances of the variable name pointed to by
 .Fa name
 from the list.
 The
 .Fn unsetenv
 function
 deletes all instances of the variable name pointed to by
 .Fa name
 from the list.

+Note that only the variable name (e.g., "NAME") should be given;
+"NAME=value" will not work.

 .Sh RETURN VALUES
 The
 .Fn getenv
 .Sh RETURN VALUES
 The
 .Fn getenv


@@ -122,53 +126,118 @@ is not in the current environment,
 .Dv NULL
 is returned.
 .Pp
 .Dv NULL
 is returned.
 .Pp

-.Rv -std setenv putenv
+.Rv -std setenv putenv unsetenv

 .Sh ERRORS
 .Bl -tag -width Er
 .Sh ERRORS
 .Bl -tag -width Er

-.It Bq Er ENOMEM
+.It Bq Er EINVAL

 The function
 The function

+.Fn getenv ,

 .Fn setenv
 or
 .Fn setenv
 or

+.Fn unsetenv
+failed because the
+.Fa name
+is a
+.Dv NULL
+pointer, points to an empty string, or points to a string containing an
+.Dq Li \&=
+character.
+.Pp
+The function

 .Fn putenv
 .Fn putenv

-failed because they were unable to allocate memory for the environment.
+failed because
+.Fa string
+is a
+.Dv NULL
+pointer or
+.Fa string
+is without an
+.Dq Li \&=
+character.
+.It Bq Er ENOMEM
+The function
+.Fn setenv ,
+.Fn unsetenv
+or
+.Fn putenv
+failed because it was unable to allocate memory for the environment.

 .El
 .El

+.Sh LEGACY SYNOPSIS
+.Fd #include <stdlib.h>
+.Pp
+.Ft void
+.br
+.Fo unsetenv
+.Fa "const char *name"
+.Fc ;
+.Pp
+.Fn unsetenv
+doesn't return a value.
+.Sh COMPATIBILITY
+.Fn putenv
+no longer copies its input buffer.
+This often appears in crash logs as a crash in
+.Fn getenv .
+Avoid passing local buffers or freeing the memory
+that is passed to
+.Fn putenv .
+Use
+.Fn setenv ,  
+which still makes an internal copy of its buffers.
+.Pp
+.Fn unsetenv
+no longer parses the variable name;
+e.g., unsetenv ("FOO=BAR") no longer works.
+Use unsetenv("FOO").
+.Fn unsetenv
+also now returns a status value and will set
+.Va errno
+to EINVAL if
+.Fa name
+is not a defined environment variable.

 .Sh SEE ALSO
 .Xr csh 1 ,
 .Xr sh 1 ,
 .Xr execve 2 ,
 .Sh SEE ALSO
 .Xr csh 1 ,
 .Xr sh 1 ,
 .Xr execve 2 ,

+.Xr compat 5 ,

 .Xr environ 7
 .Sh STANDARDS
 The
 .Fn getenv
 function conforms to
 .St -isoC .
 .Xr environ 7
 .Sh STANDARDS
 The
 .Fn getenv
 function conforms to
 .St -isoC .

+The
+.Fn setenv ,
+.Fn putenv
+and
+.Fn unsetenv
+functions conforms to
+.St -p1003.1-2001 .
+.Sh HISTORY
+The functions
+.Fn setenv
+and
+.Fn unsetenv
+appeared in
+.At v7 .
+The
+.Fn putenv
+function appeared in
+.Bx 4.3 Reno .

 .Sh BUGS
 Successive calls to
 .Fn setenv
 .Sh BUGS
 Successive calls to
 .Fn setenv

-or
-.Fn putenv
-assigning a differently sized
+that assign a larger-sized

 .Fa value
 .Fa value

-to the same
+than any previous value to the same

 .Fa name
 will result in a memory leak.
 The
 .Fx
 .Fa name
 will result in a memory leak.
 The
 .Fx

-semantics for these functions
+semantics for this function

 (namely, that the contents of
 .Fa value
 are copied and that old values remain accessible indefinitely) make this
 bug unavoidable.
 Future versions may eliminate one or both of these
 semantic guarantees in order to fix the bug.
 (namely, that the contents of
 .Fa value
 are copied and that old values remain accessible indefinitely) make this
 bug unavoidable.
 Future versions may eliminate one or both of these
 semantic guarantees in order to fix the bug.

-.Sh HISTORY
-The functions
-.Fn setenv
-and
-.Fn unsetenv
-appeared in
-.At v7 .
-The
-.Fn putenv
-function appeared in
-.Bx 4.3 Reno .