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