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.\" $OpenBSD: getenv.3,v 1.17 2012/06/02 00:14:16 guenther Exp $ 33.\" 34.Dd $Mdocdate: June 2 2012 $ 35.Dt GETENV 3 36.Os 37.Sh NAME 38.Nm getenv , 39.Nm putenv , 40.Nm setenv , 41.Nm unsetenv 42.Nd environment variable functions 43.Sh SYNOPSIS 44.Fd #include <stdlib.h> 45.Ft char * 46.Fn getenv "const char *name" 47.Ft int 48.Fn setenv "const char *name" "const char *value" "int overwrite" 49.Ft int 50.Fn putenv "char *string" 51.Ft int 52.Fn unsetenv "const char *name" 53.Sh DESCRIPTION 54These functions set, unset, and fetch environment variables from the host 55.Em environment list . 56For compatibility with differing environment conventions, the given argument 57.Fa name 58may be appended with an equal sign 59.Dq Li \&= 60followed by zero or more characters, 61and 62.Fa value 63may be prepended with an equal sign. 64.Pp 65The 66.Fn getenv 67function obtains the current value of the environment variable 68.Fa name . 69If the variable 70.Fa name 71is not in the current environment, a null pointer is returned. 72.Pp 73The 74.Fn setenv 75function inserts or resets the environment variable 76.Fa name 77in the current environment list. 78If the variable 79.Fa name 80does not exist in the list, it is inserted with the given 81.Fa value . 82If the variable does exist, the argument 83.Fa overwrite 84is tested; if 85.Fa overwrite 86is zero, the variable is not reset, otherwise it is reset to the given 87.Fa value . 88.Pp 89The 90.Fn putenv 91function takes an argument of the form 92.Ar name Ns = Ns Ar value . 93The memory pointed to by 94.Ar string 95becomes part of the environment and must not be deallocated by the caller. 96If the variable already exists, it will be overwritten. 97A common source of bugs is to pass a 98.Ar string 99argument that is a locally scoped string buffer. 100This will result in corruption of the environment after leaving 101the scope in which the variable is defined. 102For this reason, the 103.Fn setenv 104function is preferred over 105.Fn putenv . 106.Pp 107The 108.Fn unsetenv 109function deletes all instances of the variable name pointed to by 110.Fa name 111from the list. 112.Sh RETURN VALUES 113These functions 114return zero if successful; otherwise the global variable 115.Va errno 116is set to indicate the error and \-1 is returned. 117.Pp 118If 119.Fn getenv 120is successful, the string returned should be considered read-only. 121.Sh ERRORS 122.Bl -tag -width Er 123.It Bq Er EINVAL 124The 125.Fn setenv 126or 127.Fn unsetenv 128function was passed a 129.Ar name 130containing an 131.Sq = 132character. 133.Pp 134The 135.Fn unsetenv 136function was passed an empty 137.Ar name 138or a NULL pointer. 139.Pp 140The 141.Fn putenv 142function was passed a 143.Ar string 144that did not contain an 145.Sq = 146character. 147.It Bq Er ENOMEM 148The 149.Fn setenv 150or 151.Fn putenv 152function failed because it was unable to allocate memory for the environment. 153.El 154.Sh SEE ALSO 155.Xr csh 1 , 156.Xr sh 1 , 157.Xr execve 2 , 158.Xr environ 7 159.Sh STANDARDS 160The 161.Fn getenv 162function conforms to 163.St -ansiC . 164The 165.Fn putenv , 166.Fn setenv , 167and 168.Fn unsetenv 169functions conform to 170.St -p1003.1-2008 . 171.Sh HISTORY 172The function 173.Fn getenv 174appeared in 175.At v7 176and 177.Bx 3 . 178The functions 179.Fn setenv 180and 181.Fn unsetenv 182appeared in 183.Bx 4.3 Tahoe . 184The 185.Fn putenv 186function appeared in 187.Bx 4.3 Reno . 188