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 June 20, 2007
 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 is
 92  equivalent to:
 93  .Bd -literal -offset indent
 94  setenv(name, value, 1);
 95  .Ed
 96  .Pp
 97  The string pointed to by
 98  .Fa string
 99  becomes part of the environment.
100  A program should not alter or free the string,
101  and should not use stack or other transient string variables
102  as arguments to
103  .Fn putenv .
104  The
105  .Fn setenv
106  function is strongly preferred to
107  .Fn putenv .
108  .Pp
109  The
110  .Fn unsetenv
111  function
112  deletes all instances of the variable name pointed to by
113  .Fa name
114  from the list.
115  Note that only the variable name (e.g., "NAME") should be given;
116  "NAME=value" will not work.
117  .Sh RETURN VALUES
118  The
119  .Fn getenv
120  function returns the value of the environment variable as a
121  .Dv NUL Ns
122  -terminated string.
123  If the variable
124  .Fa name
125  is not in the current environment,
126  .Dv NULL
127  is returned.
128  .Pp
129  .Rv -std setenv putenv unsetenv
130  .Sh ERRORS
131  .Bl -tag -width Er
132  .It Bq Er EINVAL
133  The function
134  .Fn getenv ,
135  .Fn setenv
136  or
137  .Fn unsetenv
138  failed because the
139  .Fa name
140  is a
141  .Dv NULL
142  pointer, points to an empty string, or points to a string containing an
143  .Dq Li \&=
144  character.
145  .Pp
146  The function
147  .Fn putenv
148  failed because
149  .Fa string
150  is a
151  .Dv NULL
152  pointer or
153  .Fa string
154  is without an
155  .Dq Li \&=
156  character.
157  .It Bq Er ENOMEM
158  The function
159  .Fn setenv ,
160  .Fn unsetenv
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  The
210  .Fn setenv ,
211  .Fn putenv
212  and
213  .Fn unsetenv
214  functions conforms to
215  .St -p1003.1-2001 .
216  .Sh HISTORY
217  The functions
218  .Fn setenv
219  and
220  .Fn unsetenv
221  appeared in
222  .At v7 .
223  The
224  .Fn putenv
225  function appeared in
226  .Bx 4.3 Reno .
227  .Sh BUGS
228  Successive calls to
229  .Fn setenv
230  that assign a larger-sized
231  .Fa value
232  than any previous value to the same
233  .Fa name
234  will result in a memory leak.
235  The
236  .Fx
237  semantics for this function
238  (namely, that the contents of
239  .Fa value
240  are copied and that old values remain accessible indefinitely) make this
241  bug unavoidable.
242  Future versions may eliminate one or both of these
243  semantic guarantees in order to fix the bug.