.\" 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.
.\"
.\" SUCH DAMAGE.
.\"
.\" @(#)getenv.3 8.2 (Berkeley) 12/11/93
-.\" $FreeBSD: src/lib/libc/stdlib/getenv.3,v 1.13 2002/12/18 13:33:03 ru Exp $
+.\" $FreeBSD$
.\"
-.Dd December 11, 1993
+.Dd June 20, 2007
.Dt GETENV 3
.Os
.Sh NAME
.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 .
-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.
+The application should not modify the string pointed
+to by the
+.Fn getenv
+function.
.Pp
The
.Fn setenv
.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 .
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.
+Note that only the variable name (e.g., "NAME") should be given;
+"NAME=value" will not work.
.Sh RETURN VALUES
-.Rv -std setenv putenv
+The
+.Fn getenv
+function returns the value of the environment variable as a
+.Dv NUL Ns
+-terminated string.
+If the variable
+.Fa name
+is not in the current environment,
+.Dv NULL
+is returned.
+.Pp
+.Rv -std setenv putenv unsetenv
.Sh ERRORS
.Bl -tag -width Er
-.It Bq Er ENOMEM
+.It Bq Er EINVAL
The function
+.Fn getenv ,
.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
-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
+.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 ,
+.Xr compat 5 ,
.Xr environ 7
.Sh STANDARDS
The
.Fn getenv
function conforms to
.St -isoC .
-.Sh BUGS
-Successive calls to
-.Fn setenv
-or
+The
+.Fn setenv ,
.Fn putenv
-assigning a differently sized
-.Fa value
-to the same
-.Fa name
-will result in a memory leak. The
-.Fx
-semantics for these functions
-(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.
+and
+.Fn unsetenv
+functions conforms to
+.St -p1003.1-2001 .
.Sh HISTORY
The functions
.Fn setenv
.Fn putenv
function appeared in
.Bx 4.3 Reno .
+.Sh BUGS
+Successive calls to
+.Fn setenv
+that assign a larger-sized
+.Fa value
+than any previous value to the same
+.Fa name
+will result in a memory leak.
+The
+.Fx
+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.
projects / apple / libc.git / blobdiff