Libc-1044.40.1.tar.gz

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

diff --git a/stdlib/FreeBSD/getenv.3 b/stdlib/FreeBSD/getenv.3
index 32cdd8fa31b6b69873e7362ab4d6a45f1972cb22..6bcaa26dccf6962ec41dab631b10ed3516d78602 100644 (file)
--- a/stdlib/FreeBSD/getenv.3
+++ b/stdlib/FreeBSD/getenv.3
@@ -34,7 +34,7 @@
 .\" 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.13 2002/12/18 13:33:03 ru Exp $
+.\" $FreeBSD: src/lib/libc/stdlib/getenv.3,v 1.16 2004/07/07 19:57:13 ru Exp $

 .\"
 .Dd December 11, 1993
 .Dt GETENV 3
 .\"
 .Dd December 11, 1993
 .Dt GETENV 3


@@ -50,13 +50,23 @@
 .Sh SYNOPSIS
 .In stdlib.h
 .Ft char *
 .Sh SYNOPSIS
 .In stdlib.h
 .Ft char *

-.Fn getenv "const char *name"
+.Fo getenv
+.Fa "const char *name"
+.Fc

 .Ft int
 .Ft int

-.Fn setenv "const char *name" "const char *value" "int overwrite"
+.Fo putenv
+.Fa "char *string"
+.Fc

 .Ft int
 .Ft int

-.Fn putenv "const char *string"
-.Ft void
-.Fn unsetenv "const char *name"
+.Fo setenv
+.Fa "const char *name"
+.Fa "const char *value"
+.Fa "int overwrite"
+.Fc
+.Ft int
+.Fo unsetenv
+.Fa "const char *name"
+.Fc

 .Sh DESCRIPTION
 These functions set, unset and fetch environment variables from the
 host
 .Sh DESCRIPTION
 These functions set, unset and fetch environment variables from the
 host


@@ -70,15 +80,13 @@ may be appended and prepended,
 respectively,
 with an equal sign
 .Dq Li \&= .
 respectively,
 with an equal sign
 .Dq Li \&= .

+The behavior is undefined when an equal sign appears at any other location in
+.Fa name .

 .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 .

-If the variable
-.Fa name
-is not in the current environment,
-a null pointer is returned.

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


@@ -108,27 +116,92 @@ 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
 .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
 .Sh ERRORS
 .Bl -tag -width Er

+.It Bq Er EINVAL
+The function
+.Fn unsetenv
+failed because
+.Fa name
+was not found in the environment list.

 .It Bq Er ENOMEM
 The function
 .Fn setenv
 or
 .Fn putenv
 .It Bq Er ENOMEM
 The function
 .Fn setenv
 or
 .Fn putenv

-failed because they were unable to allocate memory for the environment.
+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
 .Xr environ 7
 .Sh STANDARDS
 The


@@ -144,13 +217,15 @@ assigning a differently sized
 .Fa value
 to the same
 .Fa name
 .Fa value
 to the same
 .Fa name

-will result in a memory leak.  The
+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
 .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
+bug unavoidable.
+Future versions may eliminate one or both of these

 semantic guarantees in order to fix the bug.
 .Sh HISTORY
 The functions
 semantic guarantees in order to fix the bug.
 .Sh HISTORY
 The functions