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.\" 4. 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: src/lib/libc/stdlib/getenv.3,v 1.27 2007/07/04 00:00:39 scf Exp $ 34.\" $DragonFly: src/lib/libc/stdlib/getenv.3,v 1.5 2006/02/17 19:35:06 swildner Exp $ 35.\" 36.Dd June 20, 2007 37.Dt GETENV 3 38.Os 39.Sh NAME 40.Nm getenv , 41.Nm putenv , 42.Nm setenv , 43.Nm unsetenv 44.Nd environment variable functions 45.Sh LIBRARY 46.Lb libc 47.Sh SYNOPSIS 48.In stdlib.h 49.Ft char * 50.Fn getenv "const char *name" 51.Ft int 52.Fn setenv "const char *name" "const char *value" "int overwrite" 53.Ft int 54.Fn putenv "char *string" 55.Ft int 56.Fn unsetenv "const char *name" 57.Sh DESCRIPTION 58These functions set, unset and fetch environment variables from the 59host 60.Em environment list . 61.Pp 62The 63.Fn getenv 64function obtains the current value of the environment variable, 65.Fa name . 66The application should not modify the string pointed 67to by the 68.Fn getenv 69function. 70.Pp 71The 72.Fn setenv 73function inserts or resets the environment variable 74.Fa name 75in the current environment list. 76If the variable 77.Fa name 78does not exist in the list, 79it is inserted with the given 80.Fa value . 81If the variable does exist, the argument 82.Fa overwrite 83is tested; if 84.Fa overwrite 85is zero, the 86variable is not reset, otherwise it is reset 87to the given 88.Fa value . 89.Pp 90The 91.Fn putenv 92function takes an argument of the form ``name=value'' and 93puts it directly into the current environment, 94so altering the argument shall change the environment. 95If the variable 96.Fa name 97does not exist in the list, 98it is inserted with the given 99.Fa value . 100If the variable 101.Fa name 102does exist, it is reset to the given 103.Fa value . 104.Pp 105The 106.Fn unsetenv 107function 108deletes all instances of the variable name pointed to by 109.Fa name 110from the list. 111.Sh RETURN VALUES 112The 113.Fn getenv 114function returns the value of the environment variable as a 115.Dv NUL Ns 116-terminated string. 117If the variable 118.Fa name 119is not in the current environment, 120.Dv NULL 121is returned. 122.Pp 123.Rv -std setenv putenv unsetenv 124.Sh ERRORS 125.Bl -tag -width Er 126.It Bq Er EINVAL 127The function 128.Fn getenv , 129.Fn setenv 130or 131.Fn unsetenv 132failed because the 133.Fa name 134is a 135.Dv NULL 136pointer, points to an empty string, or points to a string containing an 137.Dq Li \&= 138character. 139.Pp 140The function 141.Fn putenv 142failed because 143.Fa string 144is a 145.Dv NULL 146pointer, 147.Fa string is without an 148.Dq Li \&= 149character or 150.Dq Li \&= 151is the first character in 152.Fa string . 153This does not follow the 154.Tn POSIX 155specification. 156.It Bq Er ENOMEM 157The function 158.Fn setenv , 159.Fn unsetenv 160or 161.Fn putenv 162failed because they were unable to allocate memory for the environment. 163.It Bq Er EFAULT 164The functions 165.Fn setenv , 166.Fn unsetenv 167or 168.Fn putenv 169failed to make a valid copy of the environment due to the environment being 170corrupt (i.e., a name without a value). A warning will be output to stderr with 171information about the issue. 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.Dx 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