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 57These functions set, unset and fetch environment variables from the 58host 59.Em environment list . 60.Pp 61The 62.Fn getenv 63function obtains the current value of the environment variable, 64.Fa name . 65The application should not modify the string pointed 66to by the 67.Fn getenv 68function. 69.Pp 70The 71.Fn setenv 72function inserts or resets the environment variable 73.Fa name 74in the current environment list. 75If the variable 76.Fa name 77does not exist in the list, 78it is inserted with the given 79.Fa value . 80If the variable does exist, the argument 81.Fa overwrite 82is tested; if 83.Fa overwrite 84is zero, the 85variable is not reset, otherwise it is reset 86to the given 87.Fa value . 88.Pp 89The 90.Fn putenv 91function takes an argument of the form ``name=value'' and 92puts it directly into the current environment, 93so altering the argument shall change the environment. 94If the variable 95.Fa name 96does not exist in the list, 97it is inserted with the given 98.Fa value . 99If the variable 100.Fa name 101does exist, it is reset to the given 102.Fa value . 103.Pp 104The 105.Fn unsetenv 106function 107deletes all instances of the variable name pointed to by 108.Fa name 109from the list. 110.Pp 111If corruption (e.g., a name without a value) is detected while making a copy of 112environ for internal usage, then 113.Fn setenv , 114.Fn unsetenv 115and 116.Fn putenv 117will output a warning to stderr about the issue, drop the corrupt entry and 118complete the task without error. 119.Sh RETURN VALUES 120The 121.Fn getenv 122function returns the value of the environment variable as a 123.Dv NUL Ns 124-terminated string. 125If the variable 126.Fa name 127is not in the current environment, 128.Dv NULL 129is returned. 130.Pp 131.Rv -std setenv putenv unsetenv 132.Sh ERRORS 133.Bl -tag -width Er 134.It Bq Er EINVAL 135The function 136.Fn getenv , 137.Fn setenv 138or 139.Fn unsetenv 140failed because the 141.Fa name 142is a 143.Dv NULL 144pointer, points to an empty string, or points to a string containing an 145.Dq Li \&= 146character. 147.Pp 148The function 149.Fn putenv 150failed because 151.Fa string 152is a 153.Dv NULL 154pointer, 155.Fa string 156is without an 157.Dq Li \&= 158character or 159.Dq Li \&= 160is the first character in 161.Fa string . 162This does not follow the 163.Tn POSIX 164specification. 165.It Bq Er ENOMEM 166The function 167.Fn setenv , 168.Fn unsetenv 169or 170.Fn putenv 171failed 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 179The 180.Fn getenv 181function conforms to 182.St -isoC . 183The 184.Fn setenv , 185.Fn putenv 186and 187.Fn unsetenv 188functions conforms to 189.St -p1003.1-2001 . 190.Sh HISTORY 191The functions 192.Fn setenv 193and 194.Fn unsetenv 195appeared in 196.At v7 . 197The 198.Fn putenv 199function appeared in 200.Bx 4.3 Reno . 201.Pp 202Until 203.Fx 7.0 , 204.Fn putenv 205would make a copy of 206.Fa string 207and insert it into the environment using 208.Fn setenv . 209This was changed to use 210.Fa string 211as the memory location of the ``name=value'' pair to follow the 212.Tn POSIX 213specification. 214.Sh BUGS 215Successive calls to 216.Fn setenv 217that assign a larger-sized 218.Fa value 219than any previous value to the same 220.Fa name 221will result in a memory leak. 222The 223.Fx 224semantics for this function 225(namely, that the contents of 226.Fa value 227are copied and that old values remain accessible indefinitely) make this 228bug unavoidable. 229Future versions may eliminate one or both of these 230semantic guarantees in order to fix the bug. 231