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