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 fc1963287a5ed7f38c7034aaa419bf876eb92a0d..6bcaa26dccf6962ec41dab631b10ed3516d78602 100644 (file)
--- a/stdlib/FreeBSD/getenv.3
+++ b/stdlib/FreeBSD/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,6 +80,8 @@ 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
 .Pp
 The
 .Fn getenv


@@ -104,12 +116,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,20 +148,60 @@ 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 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