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: head/lib/libc/stdlib/getenv.3 251069 2013-05-28 20:57:40Z emaste $
  34 .\"
  35 .Dd September 9, 2015
  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
 156 is without an
 157 .Dq Li \&=
 158 character or
 159 .Dq Li \&=
 160 is the first character in
 161 .Fa string .
 162 This does not follow the
 163 .Tn POSIX
 164 specification.
 165 .It Bq Er ENOMEM
 166 The function
 167 .Fn setenv ,
 168 .Fn unsetenv
 169 or
 170 .Fn putenv
 171 failed because they were unable to allocate memory for the environment.
 172 .El
 173 .Sh SEE ALSO
 174 .Xr csh 1 ,
 175 .Xr sh 1 ,
 176 .Xr execve 2 ,
 177 .Xr environ 7
 178 .Sh STANDARDS
 179 The
 180 .Fn getenv
 181 function conforms to
 182 .St -isoC .
 183 The
 184 .Fn setenv ,
 185 .Fn putenv
 186 and
 187 .Fn unsetenv
 188 functions conforms to
 189 .St -p1003.1-2001 .
 190 .Sh HISTORY
 191 The functions
 192 .Fn setenv
 193 and
 194 .Fn unsetenv
 195 appeared in
 196 .At v7 .
 197 The
 198 .Fn putenv
 199 function appeared in
 200 .Bx 4.3 Reno .
 201 .Pp
 202 Until
 203 .Fx 7.0 ,
 204 .Fn putenv
 205 would make a copy of
 206 .Fa string
 207 and insert it into the environment using
 208 .Fn setenv .
 209 This was changed to use
 210 .Fa string
 211 as the memory location of the ``name=value'' pair to follow the
 212 .Tn POSIX
 213 specification.
 214 .Sh BUGS
 215 Successive calls to
 216 .Fn setenv
 217 that assign a larger-sized
 218 .Fa value
 219 than any previous value to the same
 220 .Fa name
 221 will result in a memory leak.
 222 The
 223 .Dx
 224 semantics for this function
 225 (namely, that the contents of
 226 .Fa value
 227 are copied and that old values remain accessible indefinitely) make this
 228 bug unavoidable.
 229 Future versions may eliminate one or both of these
 230 semantic guarantees in order to fix the bug.