stdlib/FreeBSD/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. All advertising materials mentioning features or use of this software
  17 .\"    must display the following acknowledgement:
  18 .\"     This product includes software developed by the University of
  19 .\"     California, Berkeley and its contributors.
  20 .\" 4. Neither the name of the University nor the names of its contributors
  21 .\"    may be used to endorse or promote products derived from this software
  22 .\"    without specific prior written permission.
  23 .\"
  24 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  25 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  26 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  27 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  28 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  29 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  30 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  31 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  32 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  33 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  34 .\" SUCH DAMAGE.
  35 .\"
  36 .\"     @(#)getenv.3    8.2 (Berkeley) 12/11/93
  37 .\" $FreeBSD: src/lib/libc/stdlib/getenv.3,v 1.16 2004/07/07 19:57:13 ru Exp $
  38 .\"
  39 .Dd December 11, 1993
  40 .Dt GETENV 3
  41 .Os
  42 .Sh NAME
  43 .Nm getenv ,
  44 .Nm putenv ,
  45 .Nm setenv ,
  46 .Nm unsetenv
  47 .Nd environment variable functions
  48 .Sh LIBRARY
  49 .Lb libc
  50 .Sh SYNOPSIS
  51 .In stdlib.h
  52 .Ft char *
  53 .Fo getenv
  54 .Fa "const char *name"
  55 .Fc
  56 .Ft int
  57 .Fo putenv
  58 .Fa "char *string"
  59 .Fc
  60 .Ft int
  61 .Fo setenv
  62 .Fa "const char *name"
  63 .Fa "const char *value"
  64 .Fa "int overwrite"
  65 .Fc
  66 .Ft int
  67 .Fo unsetenv
  68 .Fa "const char *name"
  69 .Fc
  70 .Sh DESCRIPTION
  71 These functions set, unset and fetch environment variables from the
  72 host
  73 .Em environment list .
  74 For compatibility with differing environment conventions,
  75 the given arguments
  76 .Fa name
  77 and
  78 .Fa value
  79 may be appended and prepended,
  80 respectively,
  81 with an equal sign
  82 .Dq Li \&= .
  83 The behavior is undefined when an equal sign appears at any other location in
  84 .Fa name .
  85 .Pp
  86 The
  87 .Fn getenv
  88 function obtains the current value of the environment variable,
  89 .Fa name .
  90 .Pp
  91 The
  92 .Fn setenv
  93 function inserts or resets the environment variable
  94 .Fa name
  95 in the current environment list.
  96 If the variable
  97 .Fa name
  98 does not exist in the list,
  99 it is inserted with the given
 100 .Fa value .
 101 If the variable does exist, the argument
 102 .Fa overwrite
 103 is tested; if
 104 .Fa overwrite
 105 is
 106 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 is
 114 equivalent to:
 115 .Bd -literal -offset indent
 116 setenv(name, value, 1);
 117 .Ed
 118 .Pp
 119 The string pointed to by
 120 .Fa string
 121 becomes part of the environment.
 122 A program should not alter or free the string,
 123 and should not use stack or other transient string variables
 124 as arguments to
 125 .Fn putenv .
 126 The
 127 .Fn setenv
 128 function is strongly preferred to
 129 .Fn putenv .
 130 .Pp
 131 The
 132 .Fn unsetenv
 133 function
 134 deletes all instances of the variable name pointed to by
 135 .Fa name
 136 from the list.
 137 Note that only the variable name (e.g., "NAME") should be given;
 138 "NAME=value" will not work.
 139 .Sh RETURN VALUES
 140 The
 141 .Fn getenv
 142 function returns the value of the environment variable as a
 143 .Dv NUL Ns
 144 -terminated string.
 145 If the variable
 146 .Fa name
 147 is not in the current environment,
 148 .Dv NULL
 149 is returned.
 150 .Pp
 151 .Rv -std setenv putenv unsetenv
 152 .Sh ERRORS
 153 .Bl -tag -width Er
 154 .It Bq Er EINVAL
 155 The function
 156 .Fn unsetenv
 157 failed because
 158 .Fa name
 159 was not found in the environment list.
 160 .It Bq Er ENOMEM
 161 The function
 162 .Fn setenv
 163 or
 164 .Fn putenv
 165 failed because it was unable to allocate memory for the environment.
 166 .El
 167 .Sh LEGACY SYNOPSIS
 168 .Fd #include <stdlib.h>
 169 .Pp
 170 .Ft void
 171 .br
 172 .Fo unsetenv
 173 .Fa "const char *name"
 174 .Fc ;
 175 .Pp
 176 .Fn unsetenv
 177 doesn't return a value.
 178 .Sh COMPATIBILITY
 179 .Fn putenv
 180 no longer copies its input buffer.
 181 This often appears in crash logs as a crash in
 182 .Fn getenv .
 183 Avoid passing local buffers or freeing the memory
 184 that is passed to
 185 .Fn putenv .
 186 Use
 187 .Fn setenv ,
 188 which still makes an internal copy of its buffers.
 189 .Pp
 190 .Fn unsetenv
 191 no longer parses the variable name;
 192 e.g., unsetenv ("FOO=BAR") no longer works.
 193 Use unsetenv("FOO").
 194 .Fn unsetenv
 195 also now returns a status value and will set
 196 .Va errno
 197 to EINVAL if
 198 .Fa name
 199 is not a defined environment variable.
 200 .Sh SEE ALSO
 201 .Xr csh 1 ,
 202 .Xr sh 1 ,
 203 .Xr execve 2 ,
 204 .Xr compat 5 ,
 205 .Xr environ 7
 206 .Sh STANDARDS
 207 The
 208 .Fn getenv
 209 function conforms to
 210 .St -isoC .
 211 .Sh BUGS
 212 Successive calls to
 213 .Fn setenv
 214 or
 215 .Fn putenv
 216 assigning a differently sized
 217 .Fa value
 218 to the same
 219 .Fa name
 220 will result in a memory leak.
 221 The
 222 .Fx
 223 semantics for these functions
 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.
 230 .Sh HISTORY
 231 The functions
 232 .Fn setenv
 233 and
 234 .Fn unsetenv
 235 appeared in
 236 .At v7 .
 237 The
 238 .Fn putenv
 239 function appeared in
 240 .Bx 4.3 Reno .