stdlib/FreeBSD/getenv.3.patch

   1 --- getenv.3    2004-11-25 11:38:41.000000000 -0800
   2 +++ getenv.3.edit       2006-09-17 20:33:52.000000000 -0700
   3 @@ -50,13 +50,23 @@
   4  .Sh SYNOPSIS
   5  .In stdlib.h
   6  .Ft char *
   7 -.Fn getenv "const char *name"
   8 +.Fo getenv
   9 +.Fa "const char *name"
  10 +.Fc
  11  .Ft int
  12 -.Fn setenv "const char *name" "const char *value" "int overwrite"
  13 +.Fo putenv
  14 +.Fa "char *string"
  15 +.Fc
  16  .Ft int
  17 -.Fn putenv "const char *string"
  18 -.Ft void
  19 -.Fn unsetenv "const char *name"
  20 +.Fo setenv
  21 +.Fa "const char *name"
  22 +.Fa "const char *value"
  23 +.Fa "int overwrite"
  24 +.Fc
  25 +.Ft int
  26 +.Fo unsetenv
  27 +.Fa "const char *name"
  28 +.Fc
  29  .Sh DESCRIPTION
  30  These functions set, unset and fetch environment variables from the
  31  host
  32 @@ -104,12 +114,26 @@
  33  setenv(name, value, 1);
  34  .Ed
  35  .Pp
  36 +The string pointed to by
  37 +.Fa string
  38 +becomes part of the environment.
  39 +A program should not alter or free the string,
  40 +and should not use stack or other transient string variables
  41 +as arguments to
  42 +.Fn putenv .
  43 +The
  44 +.Fn setenv
  45 +function is strongly preferred to
  46 +.Fn putenv .
  47 +.Pp
  48  The
  49  .Fn unsetenv
  50  function
  51  deletes all instances of the variable name pointed to by
  52  .Fa name
  53  from the list.
  54 +Note that only the variable name (e.g., "NAME") should be given;
  55 +"NAME=value" will not work.
  56  .Sh RETURN VALUES
  57  The
  58  .Fn getenv
  59 @@ -122,20 +146,60 @@
  60  .Dv NULL
  61  is returned.
  62  .Pp
  63 -.Rv -std setenv putenv
  64 +.Rv -std setenv putenv unsetenv
  65  .Sh ERRORS
  66  .Bl -tag -width Er
  67 +.It Bq Er EINVAL
  68 +The function
  69 +.Fn unsetenv
  70 +failed because
  71 +.Fa name
  72 +was not found in the environment list.
  73  .It Bq Er ENOMEM
  74  The function
  75  .Fn setenv
  76  or
  77  .Fn putenv
  78 -failed because they were unable to allocate memory for the environment.
  79 +failed because it was unable to allocate memory for the environment.
  80  .El
  81 +.Sh LEGACY SYNOPSIS
  82 +.Fd #include <stdlib.h>
  83 +.Pp
  84 +.Ft void
  85 +.br
  86 +.Fo unsetenv
  87 +.Fa "const char *name"
  88 +.Fc ;
  89 +.Pp
  90 +.Fn unsetenv
  91 +doesn't return a value.
  92 +.Sh COMPATIBILITY
  93 +.Fn putenv
  94 +no longer copies its input buffer.
  95 +This often appears in crash logs as a crash in
  96 +.Fn getenv .
  97 +Avoid passing local buffers or freeing the memory
  98 +that is passed to
  99 +.Fn putenv .
 100 +Use
 101 +.Fn setenv ,
 102 +which still makes an internal copy of its buffers.
 103 +.Pp
 104 +.Fn unsetenv
 105 +no longer parses the variable name;
 106 +e.g., unsetenv ("FOO=BAR") no longer works.
 107 +Use unsetenv("FOO").
 108 +.Fn unsetenv
 109 +also now returns a status value and will set
 110 +.Va errno
 111 +to EINVAL if
 112 +.Fa name
 113 +is not a defined environment variable.
 114  .Sh SEE ALSO
 115  .Xr csh 1 ,
 116  .Xr sh 1 ,
 117  .Xr execve 2 ,
 118 +.Xr compat 5 ,
 119  .Xr environ 7
 120  .Sh STANDARDS
 121  The