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$ 34.\" 35.Dd October 12, 2006 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 "const char *string" 54.Ft void 55.Fn unsetenv "const char *name" 56.Sh DESCRIPTION 57These functions set, unset and fetch environment variables from the 58host 59.Em environment list . 60For compatibility with differing environment conventions, 61the given arguments 62.Fa name 63and 64.Fa value 65may be appended and prepended, 66respectively, 67with an equal sign 68.Dq Li \&= . 69.Pp 70The 71.Fn getenv 72function obtains the current value of the environment variable, 73.Fa name . 74The application should not modify the string pointed 75to by the 76.Fn getenv 77function. 78.Pp 79The 80.Fn setenv 81function inserts or resets the environment variable 82.Fa name 83in the current environment list. 84If the variable 85.Fa name 86does not exist in the list, 87it is inserted with the given 88.Fa value . 89If the variable does exist, the argument 90.Fa overwrite 91is tested; if 92.Fa overwrite 93is zero, the 94variable is not reset, otherwise it is reset 95to the given 96.Fa value . 97.Pp 98The 99.Fn putenv 100function takes an argument of the form ``name=value'' and is 101equivalent to: 102.Bd -literal -offset indent 103setenv(name, value, 1); 104.Ed 105.Pp 106The 107.Fn unsetenv 108function 109deletes all instances of the variable name pointed to by 110.Fa name 111from the list. 112.Sh RETURN VALUES 113The 114.Fn getenv 115function returns the value of the environment variable as a 116.Dv NUL Ns 117-terminated string. 118If the variable 119.Fa name 120is not in the current environment, 121.Dv NULL 122is returned. 123.Pp 124.Rv -std setenv putenv 125.Sh ERRORS 126.Bl -tag -width Er 127.It Bq Er ENOMEM 128The function 129.Fn setenv 130or 131.Fn putenv 132failed because they were unable to allocate memory for the environment. 133.El 134.Sh SEE ALSO 135.Xr csh 1 , 136.Xr sh 1 , 137.Xr execve 2 , 138.Xr environ 7 139.Sh STANDARDS 140The 141.Fn getenv 142function conforms to 143.St -isoC . 144.Sh HISTORY 145The functions 146.Fn setenv 147and 148.Fn unsetenv 149appeared in 150.At v7 . 151The 152.Fn putenv 153function appeared in 154.Bx 4.3 Reno . 155.Sh BUGS 156Successive calls to 157.Fn setenv 158or 159.Fn putenv 160assigning a differently sized 161.Fa value 162to the same 163.Fa name 164will result in a memory leak. 165The 166.Fx 167semantics for these functions 168(namely, that the contents of 169.Fa value 170are copied and that old values remain accessible indefinitely) make this 171bug unavoidable. 172Future versions may eliminate one or both of these 173semantic guarantees in order to fix the bug. 174