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 .Sh RETURN VALUES
 111 The
 112 .Fn getenv
 113 function returns the value of the environment variable as a
 114 .Dv NUL Ns
 115 -terminated string.
 116 If the variable
 117 .Fa name
 118 is not in the current environment,
 119 .Dv NULL
 120 is returned.
 121 .Pp
 122 .Rv -std setenv putenv unsetenv
 123 .Sh ERRORS
 124 .Bl -tag -width Er
 125 .It Bq Er EINVAL
 126 The function
 127 .Fn getenv ,
 128 .Fn setenv
 129 or
 130 .Fn unsetenv
 131 failed because the
 132 .Fa name
 133 is a
 134 .Dv NULL
 135 pointer, points to an empty string, or points to a string containing an
 136 .Dq Li \&=
 137 character.
 138 .Pp
 139 The function
 140 .Fn putenv
 141 failed because
 142 .Fa string
 143 is a
 144 .Dv NULL
 145 pointer,
 146 .Fa string is without an
 147 .Dq Li \&=
 148 character or
 149 .Dq Li \&=
 150 is the first character in
 151 .Fa string .
 152 This does not follow the
 153 .Tn POSIX
 154 specification.
 155 .It Bq Er ENOMEM
 156 The function
 157 .Fn setenv ,
 158 .Fn unsetenv
 159 or
 160 .Fn putenv
 161 failed because they were unable to allocate memory for the environment.
 162 .It Bq Er EFAULT
 163 The functions
 164 .Fn setenv ,
 165 .Fn unsetenv
 166 or
 167 .Fn putenv
 168 failed to make a valid copy of the environment due to the environment being
 169 corrupt (i.e., a name without a value).  A warning will be output to stderr with
 170 information about the issue.
 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.