lib/libc/stdlib/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 .\" 4. 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
  92 puts it directly into the current environment,
  93 so altering the argument shall change the environment.
  94 If the variable
  95 .Fa name
  96 does not exist in the list,
  97 it is inserted with the given
  98 .Fa value .
  99 If the variable
 100 .Fa name
 101 does exist, it is reset to the given
 102 .Fa value .
 103 .Pp
 104 The
 105 .Fn unsetenv
 106 function
 107 deletes all instances of the variable name pointed to by
 108 .Fa name
 109 from the list.
 110 .Pp
 111 If corruption (e.g., a name without a value) is detected while making a copy of
 112 environ for internal usage, then
 113 .Fn setenv ,
 114 .Fn unsetenv
 115 and
 116 .Fn putenv
 117 will output a warning to stderr about the issue, drop the corrupt entry and
 118 complete the task without error.
 119 .Sh RETURN VALUES
 120 The
 121 .Fn getenv
 122 function returns the value of the environment variable as a
 123 .Dv NUL Ns
 124 -terminated string.
 125 If the variable
 126 .Fa name
 127 is not in the current environment,
 128 .Dv NULL
 129 is returned.
 130 .Pp
 131 .Rv -std setenv putenv unsetenv
 132 .Sh ERRORS
 133 .Bl -tag -width Er
 134 .It Bq Er EINVAL
 135 The function
 136 .Fn getenv ,
 137 .Fn setenv
 138 or
 139 .Fn unsetenv
 140 failed because the
 141 .Fa name
 142 is a
 143 .Dv NULL
 144 pointer, points to an empty string, or points to a string containing an
 145 .Dq Li \&=
 146 character.
 147 .Pp
 148 The function
 149 .Fn putenv
 150 failed because
 151 .Fa string
 152 is a
 153 .Dv NULL
 154 pointer,
 155 .Fa string is without an
 156 .Dq Li \&=
 157 character or
 158 .Dq Li \&=
 159 is the first character in
 160 .Fa string .
 161 This does not follow the
 162 .Tn POSIX
 163 specification.
 164 .It Bq Er ENOMEM
 165 The function
 166 .Fn setenv ,
 167 .Fn unsetenv
 168 or
 169 .Fn putenv
 170 failed because they were unable to allocate memory for the environment.
 171 .El
 172 .Sh SEE ALSO
 173 .Xr csh 1 ,
 174 .Xr sh 1 ,
 175 .Xr execve 2 ,
 176 .Xr environ 7
 177 .Sh STANDARDS
 178 The
 179 .Fn getenv
 180 function conforms to
 181 .St -isoC .
 182 The
 183 .Fn setenv ,
 184 .Fn putenv
 185 and
 186 .Fn unsetenv
 187 functions conforms to
 188 .St -p1003.1-2001 .
 189 .Sh HISTORY
 190 The functions
 191 .Fn setenv
 192 and
 193 .Fn unsetenv
 194 appeared in
 195 .At v7 .
 196 The
 197 .Fn putenv
 198 function appeared in
 199 .Bx 4.3 Reno .
 200 .Pp
 201 Until
 202 .Fx 7.0 ,
 203 .Fn putenv
 204 would make a copy of
 205 .Fa string
 206 and insert it into the environment using
 207 .Fn setenv .
 208 This was changed to use
 209 .Fa string
 210 as the memory location of the ``name=value'' pair to follow the
 211 .Tn POSIX
 212 specification.
 213 .Sh BUGS
 214 Successive calls to
 215 .Fn setenv
 216 that assign a larger-sized
 217 .Fa value
 218 than any previous value to the same
 219 .Fa name
 220 will result in a memory leak.
 221 The
 222 .Fx
 223 semantics for this function
 224 (namely, that the contents of
 225 .Fa value
 226 are copied and that old values remain accessible indefinitely) make this
 227 bug unavoidable.
 228 Future versions may eliminate one or both of these
 229 semantic guarantees in order to fix the bug.