stdlib/FreeBSD/getenv.3

   1 .\" Copyright (c) 1988, 1991, 1993
   2 .\"     The Regents of the University of California.  All rights reserved.
   3 .\"
   4 .\" This code is derived from software contributed to Berkeley by
   5 .\" the American National Standards Committee X3, on Information
   6 .\" Processing Systems.
   7 .\"
   8 .\" Redistribution and use in source and binary forms, with or without
   9 .\" modification, are permitted provided that the following conditions
  10 .\" are met:
  11 .\" 1. Redistributions of source code must retain the above copyright
  12 .\"    notice, this list of conditions and the following disclaimer.
  13 .\" 2. Redistributions in binary form must reproduce the above copyright
  14 .\"    notice, this list of conditions and the following disclaimer in the
  15 .\"    documentation and/or other materials provided with the distribution.
  16 .\" 3. Neither the name of the University nor the names of its contributors
  17 .\"    may be used to endorse or promote products derived from this software
  18 .\"    without specific prior written permission.
  19 .\"
  20 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  21 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  22 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  23 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  24 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  25 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  26 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  27 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  28 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  29 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  30 .\" SUCH DAMAGE.
  31 .\"
  32 .\"     @(#)getenv.3    8.2 (Berkeley) 12/11/93
  33 .\" $FreeBSD$
  34 .\"
  35 .Dd June 20, 2007
  36 .Dt GETENV 3
  37 .Os
  38 .Sh NAME
  39 .Nm getenv ,
  40 .Nm putenv ,
  41 .Nm setenv ,
  42 .Nm unsetenv
  43 .Nd environment variable functions
  44 .Sh LIBRARY
  45 .Lb libc
  46 .Sh SYNOPSIS
  47 .In stdlib.h
  48 .Ft char *
  49 .Fn getenv "const char *name"
  50 .Ft int
  51 .Fn setenv "const char *name" "const char *value" "int overwrite"
  52 .Ft int
  53 .Fn putenv "char *string"
  54 .Ft int
  55 .Fn unsetenv "const char *name"
  56 .Sh DESCRIPTION
  57 These functions set, unset and fetch environment variables from the
  58 host
  59 .Em environment list .
  60 .Pp
  61 The
  62 .Fn getenv
  63 function obtains the current value of the environment variable,
  64 .Fa name .
  65 The application should not modify the string pointed
  66 to by the
  67 .Fn getenv
  68 function.
  69 .Pp
  70 The
  71 .Fn setenv
  72 function inserts or resets the environment variable
  73 .Fa name
  74 in the current environment list.
  75 If the variable
  76 .Fa name
  77 does not exist in the list,
  78 it is inserted with the given
  79 .Fa value .
  80 If the variable does exist, the argument
  81 .Fa overwrite
  82 is tested; if
  83 .Fa overwrite
  84 is zero, the
  85 variable is not reset, otherwise it is reset
  86 to the given
  87 .Fa value .
  88 .Pp
  89 The
  90 .Fn putenv
  91 function takes an argument of the form ``name=value'' and is
  92 equivalent to:
  93 .Bd -literal -offset indent
  94 setenv(name, value, 1);
  95 .Ed
  96 .Pp
  97 The string pointed to by
  98 .Fa string
  99 becomes part of the environment.
 100 A program should not alter or free the string,
 101 and should not use stack or other transient string variables
 102 as arguments to
 103 .Fn putenv .
 104 The
 105 .Fn setenv
 106 function is strongly preferred to
 107 .Fn putenv .
 108 .Pp
 109 The
 110 .Fn unsetenv
 111 function
 112 deletes all instances of the variable name pointed to by
 113 .Fa name
 114 from the list.
 115 Note that only the variable name (e.g., "NAME") should be given;
 116 "NAME=value" will not work.
 117 .Sh RETURN VALUES
 118 The
 119 .Fn getenv
 120 function returns the value of the environment variable as a
 121 .Dv NUL Ns
 122 -terminated string.
 123 If the variable
 124 .Fa name
 125 is not in the current environment,
 126 .Dv NULL
 127 is returned.
 128 .Pp
 129 .Rv -std setenv putenv unsetenv
 130 .Sh ERRORS
 131 .Bl -tag -width Er
 132 .It Bq Er EINVAL
 133 The function
 134 .Fn getenv ,
 135 .Fn setenv
 136 or
 137 .Fn unsetenv
 138 failed because the
 139 .Fa name
 140 is a
 141 .Dv NULL
 142 pointer, points to an empty string, or points to a string containing an
 143 .Dq Li \&=
 144 character.
 145 .Pp
 146 The function
 147 .Fn putenv
 148 failed because
 149 .Fa string
 150 is a
 151 .Dv NULL
 152 pointer or
 153 .Fa string
 154 is without an
 155 .Dq Li \&=
 156 character.
 157 .It Bq Er ENOMEM
 158 The function
 159 .Fn setenv ,
 160 .Fn unsetenv
 161 or
 162 .Fn putenv
 163 failed because it was unable to allocate memory for the environment.
 164 .El
 165 .Sh LEGACY SYNOPSIS
 166 .Fd #include <stdlib.h>
 167 .Pp
 168 .Ft void
 169 .br
 170 .Fo unsetenv
 171 .Fa "const char *name"
 172 .Fc ;
 173 .Pp
 174 .Fn unsetenv
 175 doesn't return a value.
 176 .Sh COMPATIBILITY
 177 .Fn putenv
 178 no longer copies its input buffer.
 179 This often appears in crash logs as a crash in
 180 .Fn getenv .
 181 Avoid passing local buffers or freeing the memory
 182 that is passed to
 183 .Fn putenv .
 184 Use
 185 .Fn setenv ,
 186 which still makes an internal copy of its buffers.
 187 .Pp
 188 .Fn unsetenv
 189 no longer parses the variable name;
 190 e.g., unsetenv ("FOO=BAR") no longer works.
 191 Use unsetenv("FOO").
 192 .Fn unsetenv
 193 also now returns a status value and will set
 194 .Va errno
 195 to EINVAL if
 196 .Fa name
 197 is not a defined environment variable.
 198 .Sh SEE ALSO
 199 .Xr csh 1 ,
 200 .Xr sh 1 ,
 201 .Xr execve 2 ,
 202 .Xr compat 5 ,
 203 .Xr environ 7
 204 .Sh STANDARDS
 205 The
 206 .Fn getenv
 207 function conforms to
 208 .St -isoC .
 209 The
 210 .Fn setenv ,
 211 .Fn putenv
 212 and
 213 .Fn unsetenv
 214 functions conforms to
 215 .St -p1003.1-2001 .
 216 .Sh HISTORY
 217 The functions
 218 .Fn setenv
 219 and
 220 .Fn unsetenv
 221 appeared in
 222 .At v7 .
 223 The
 224 .Fn putenv
 225 function appeared in
 226 .Bx 4.3 Reno .
 227 .Sh BUGS
 228 Successive calls to
 229 .Fn setenv
 230 that assign a larger-sized
 231 .Fa value
 232 than any previous value to the same
 233 .Fa name
 234 will result in a memory leak.
 235 The
 236 .Fx
 237 semantics for this function
 238 (namely, that the contents of
 239 .Fa value
 240 are copied and that old values remain accessible indefinitely) make this
 241 bug unavoidable.
 242 Future versions may eliminate one or both of these
 243 semantic guarantees in order to fix the bug.