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. 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 .Pp
  84 The
  85 .Fn getenv
  86 function obtains the current value of the environment variable,
  87 .Fa name .
  88 .Pp
  89 The
  90 .Fn setenv
  91 function inserts or resets the environment variable
  92 .Fa name
  93 in the current environment list.
  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 does exist, the argument
 100 .Fa overwrite
 101 is tested; if
 102 .Fa overwrite
 103 is
 104 zero, the
 105 variable is not reset, otherwise it is reset
 106 to the given
 107 .Fa value .
 108 .Pp
 109 The
 110 .Fn putenv
 111 function takes an argument of the form ``name=value'' and is
 112 equivalent to:
 113 .Bd -literal -offset indent
 114 setenv(name, value, 1);
 115 .Ed
 116 .Pp
 117 The string pointed to by
 118 .Fa string
 119 becomes part of the environment.
 120 A program should not alter or free the string,
 121 and should not use stack or other transient string variables
 122 as arguments to
 123 .Fn putenv .
 124 The
 125 .Fn setenv
 126 function is strongly preferred to
 127 .Fn putenv .
 128 .Pp
 129 The
 130 .Fn unsetenv
 131 function
 132 deletes all instances of the variable name pointed to by
 133 .Fa name
 134 from the list.
 135 Note that only the variable name (e.g., "NAME") should be given;
 136 "NAME=value" will not work.
 137 .Sh RETURN VALUES
 138 The
 139 .Fn getenv
 140 function returns the value of the environment variable as a
 141 .Dv NUL Ns
 142 -terminated string.
 143 If the variable
 144 .Fa name
 145 is not in the current environment,
 146 .Dv NULL
 147 is returned.
 148 .Pp
 149 .Rv -std setenv putenv unsetenv
 150 .Sh ERRORS
 151 .Bl -tag -width Er
 152 .It Bq Er EINVAL
 153 The function
 154 .Fn unsetenv
 155 failed because
 156 .Fa name
 157 was not found in the environment list.
 158 .It Bq Er ENOMEM
 159 The function
 160 .Fn setenv
 161 or
 162 .Fn putenv
 163 failed because it was unable to allocate memory for the environment.
 164 .El
 165 .Sh LEGACY SYNOPSIS
 166 .Fd #include <stdlib.h>
 167 .Pp
 168 .Ft void
 169 .br
 170 .Fo unsetenv
 171 .Fa "const char *name"
 172 .Fc ;
 173 .Pp
 174 .Fn unsetenv
 175 doesn't return a value.
 176 .Sh COMPATIBILITY
 177 .Fn putenv
 178 no longer copies its input buffer.
 179 This often appears in crash logs as a crash in
 180 .Fn getenv .
 181 Avoid passing local buffers or freeing the memory
 182 that is passed to
 183 .Fn putenv .
 184 Use
 185 .Fn setenv ,
 186 which still makes an internal copy of its buffers.
 187 .Pp
 188 .Fn unsetenv
 189 no longer parses the variable name;
 190 e.g., unsetenv ("FOO=BAR") no longer works.
 191 Use unsetenv("FOO").
 192 .Fn unsetenv
 193 also now returns a status value and will set
 194 .Va errno
 195 to EINVAL if
 196 .Fa name
 197 is not a defined environment variable.
 198 .Sh SEE ALSO
 199 .Xr csh 1 ,
 200 .Xr sh 1 ,
 201 .Xr execve 2 ,
 202 .Xr compat 5 ,
 203 .Xr environ 7
 204 .Sh STANDARDS
 205 The
 206 .Fn getenv
 207 function conforms to
 208 .St -isoC .
 209 .Sh BUGS
 210 Successive calls to
 211 .Fn setenv
 212 or
 213 .Fn putenv
 214 assigning a differently sized
 215 .Fa value
 216 to the same
 217 .Fa name
 218 will result in a memory leak.
 219 The
 220 .Fx
 221 semantics for these functions
 222 (namely, that the contents of
 223 .Fa value
 224 are copied and that old values remain accessible indefinitely) make this
 225 bug unavoidable.
 226 Future versions may eliminate one or both of these
 227 semantic guarantees in order to fix the bug.
 228 .Sh HISTORY
 229 The functions
 230 .Fn setenv
 231 and
 232 .Fn unsetenv
 233 appeared in
 234 .At v7 .
 235 The
 236 .Fn putenv
 237 function appeared in
 238 .Bx 4.3 Reno .