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 .\" 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 .Dd March 14, 2023
  33 .Dt GETENV 3
  34 .Os
  35 .Sh NAME
  36 .Nm clearenv ,
  37 .Nm getenv ,
  38 .Nm putenv ,
  39 .Nm secure_getenv ,
  40 .Nm setenv ,
  41 .Nm unsetenv
  42 .Nd environment variable functions
  43 .Sh LIBRARY
  44 .Lb libc
  45 .Sh SYNOPSIS
  46 .In stdlib.h
  47 .Ft int
  48 .Fn clearenv "void"
  49 .Ft char *
  50 .Fn getenv "const char *name"
  51 .Ft char *
  52 .Fn secure_getenv "const char *name"
  53 .Ft int
  54 .Fn setenv "const char *name" "const char *value" "int overwrite"
  55 .Ft int
  56 .Fn putenv "char *string"
  57 .Ft int
  58 .Fn unsetenv "const char *name"
  59 .Sh DESCRIPTION
  60 These functions set, unset and fetch environment variables from the
  61 host
  62 .Em environment list .
  63 .Pp
  64 The
  65 .Fn clearenv
  66 function clears all environment variables.
  67 New variables can be added using
  68 .Fn setenv
  69 and
  70 .Fn putenv .
  71 .Pp
  72 The
  73 .Fn getenv
  74 function obtains the current value of the environment variable,
  75 .Fa name .
  76 The application should not modify the string pointed
  77 to by the
  78 .Fn getenv
  79 function.
  80 .Pp
  81 The
  82 .Fn secure_getenv
  83 returns
  84 .Va NULL
  85 when the environment cannot be trusted, otherwise it acts like
  86 .Fn getenv .
  87 The environment currently is not trusted when
  88 .Xr issetugid 3
  89 returns a non-zero value, but other conditions may be added
  90 in the future.
  91 .Pp
  92 The
  93 .Fn setenv
  94 function inserts or resets the environment variable
  95 .Fa name
  96 in the current environment list.
  97 If the variable
  98 .Fa name
  99 does not exist in the list,
 100 it is inserted with the given
 101 .Fa value .
 102 If the variable does exist, the argument
 103 .Fa overwrite
 104 is tested; if
 105 .Fa overwrite
 106 is zero, the
 107 variable is not reset, otherwise it is reset
 108 to the given
 109 .Fa value .
 110 .Pp
 111 The
 112 .Fn putenv
 113 function takes an argument of the form ``name=value'' and
 114 puts it directly into the current environment,
 115 so altering the argument shall change the environment.
 116 If the variable
 117 .Fa name
 118 does not exist in the list,
 119 it is inserted with the given
 120 .Fa value .
 121 If the variable
 122 .Fa name
 123 does exist, it is reset to the given
 124 .Fa value .
 125 .Pp
 126 The
 127 .Fn unsetenv
 128 function
 129 deletes all instances of the variable name pointed to by
 130 .Fa name
 131 from the list.
 132 .Pp
 133 If corruption (e.g., a name without a value) is detected while making a copy of
 134 environ for internal usage, then
 135 .Fn setenv ,
 136 .Fn unsetenv
 137 and
 138 .Fn putenv
 139 will output a warning to stderr about the issue, drop the corrupt entry and
 140 complete the task without error.
 141 .Sh RETURN VALUES
 142 The
 143 .Fn getenv
 144 function returns the value of the environment variable as a
 145 .Dv NUL Ns
 146 -terminated string.
 147 If the variable
 148 .Fa name
 149 is not in the current environment,
 150 .Dv NULL
 151 is returned.
 152 .Pp
 153 The
 154 .Fn secure_getenv
 155 function returns
 156 .Dv NULL
 157 if the process is in "secure execution," otherwise it will call
 158 .Fn getenv .
 159 .Pp
 160 .Rv -std clearenv setenv putenv unsetenv
 161 .Sh ERRORS
 162 .Bl -tag -width Er
 163 .It Bq Er EINVAL
 164 The function
 165 .Fn getenv ,
 166 .Fn setenv
 167 or
 168 .Fn unsetenv
 169 failed because the
 170 .Fa name
 171 is a
 172 .Dv NULL
 173 pointer, points to an empty string, or points to a string containing an
 174 .Dq Li \&=
 175 character.
 176 .Pp
 177 The function
 178 .Fn putenv
 179 failed because
 180 .Fa string
 181 is a
 182 .Dv NULL
 183 pointer,
 184 .Fa string
 185 is without an
 186 .Dq Li \&=
 187 character or
 188 .Dq Li \&=
 189 is the first character in
 190 .Fa string .
 191 This does not follow the
 192 .Tn POSIX
 193 specification.
 194 .It Bq Er ENOMEM
 195 The function
 196 .Fn setenv ,
 197 .Fn unsetenv
 198 or
 199 .Fn putenv
 200 failed because they were unable to allocate memory for the environment.
 201 .El
 202 .Sh SEE ALSO
 203 .Xr csh 1 ,
 204 .Xr sh 1 ,
 205 .Xr execve 2 ,
 206 .Xr environ 7
 207 .Sh STANDARDS
 208 The
 209 .Fn getenv
 210 function conforms to
 211 .St -isoC .
 212 The
 213 .Fn setenv ,
 214 .Fn putenv
 215 and
 216 .Fn unsetenv
 217 functions conforms to
 218 .St -p1003.1-2001 .
 219 The
 220 .Fn secure_getenv
 221 function is expected to be glibc-compatible.
 222 .Sh HISTORY
 223 The functions
 224 .Fn setenv
 225 and
 226 .Fn unsetenv
 227 appeared in
 228 .At v7 .
 229 The
 230 .Fn putenv
 231 function appeared in
 232 .Bx 4.3 Reno .
 233 .Pp
 234 Until
 235 .Fx 7.0 ,
 236 .Fn putenv
 237 would make a copy of
 238 .Fa string
 239 and insert it into the environment using
 240 .Fn setenv .
 241 This was changed to use
 242 .Fa string
 243 as the memory location of the ``name=value'' pair to follow the
 244 .Tn POSIX
 245 specification.
 246 .Pp
 247 The
 248 .Fn clearenv
 249 and
 250 .Fn secure_getenv
 251 functions were added in
 252 .Fx 14 .
 253 .Sh BUGS
 254 Successive calls to
 255 .Fn setenv
 256 that assign a larger-sized
 257 .Fa value
 258 than any previous value to the same
 259 .Fa name
 260 will result in a memory leak.
 261 The
 262 .Fx
 263 semantics for this function
 264 (namely, that the contents of
 265 .Fa value
 266 are copied and that old values remain accessible indefinitely) make this
 267 bug unavoidable.
 268 Future versions may eliminate one or both of these
 269 semantic guarantees in order to fix the bug.