1.\" $NetBSD: getenv.3,v 1.19 2005/09/26 10:56:54 wiz Exp $ 2.\" 3.\" Copyright (c) 1988, 1991, 1993 4.\" The Regents of the University of California. All rights reserved. 5.\" 6.\" This code is derived from software contributed to Berkeley by 7.\" the American National Standards Committee X3, on Information 8.\" Processing Systems. 9.\" 10.\" Redistribution and use in source and binary forms, with or without 11.\" modification, are permitted provided that the following conditions 12.\" are met: 13.\" 1. Redistributions of source code must retain the above copyright 14.\" notice, this list of conditions and the following disclaimer. 15.\" 2. Redistributions in binary form must reproduce the above copyright 16.\" notice, this list of conditions and the following disclaimer in the 17.\" documentation and/or other materials provided with the distribution. 18.\" 3. Neither the name of the University nor the names of its contributors 19.\" may be used to endorse or promote products derived from this software 20.\" without specific prior written permission. 21.\" 22.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 23.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 24.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 25.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 26.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 27.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 28.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 29.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 30.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 31.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 32.\" SUCH DAMAGE. 33.\" 34.\" from: @(#)getenv.3 8.2 (Berkeley) 12/11/93 35.\" 36.Dd September 25, 2005 37.Dt GETENV 3 38.Os 39.Sh NAME 40.Nm getenv , 41.Nm getenv_r , 42.Nm putenv , 43.Nm setenv , 44.Nm unsetenv 45.Nd environment variable functions 46.Sh LIBRARY 47.Lb libc 48.Sh SYNOPSIS 49.In stdlib.h 50.Ft char * 51.Fn getenv "const char *name" 52.Ft int 53.Fn getenv_r "const char *name" "char *buf" "size_t len" 54.Ft int 55.Fn setenv "const char *name" "const char *value" "int overwrite" 56.Ft int 57.Fn putenv "const char *string" 58.Ft int 59.Fn unsetenv "const char *name" 60.Sh DESCRIPTION 61These functions set, unset and fetch environment variables from the 62host 63.Em environment list . 64For compatibility with differing environment conventions, 65the given arguments 66.Ar name 67and 68.Ar value 69may be appended and prepended, 70respectively, 71with an equal sign 72.Dq Li \&= , 73except for 74.Fn unsetenv . 75.Pp 76The 77.Fn getenv 78function obtains the current value of the environment variable 79.Ar name . 80If the variable 81.Ar name 82is not in the current environment, a 83.Dv NULL 84pointer is returned. 85.Pp 86The 87.Fn getenv_r 88function obtains the current value of the environment variable 89.Fa name 90and copies it to 91.Fa buf . 92If 93.Fa name 94is not in the current environment, or the string length of the value of 95.Fa name 96is longer than 97.Fa len 98characters, then \-1 is returned and 99.Va errno 100is set to indicate the error. 101.Pp 102The 103.Fn setenv 104function inserts or resets the environment variable 105.Ar name 106in the current environment list. 107If the variable 108.Ar name 109does not exist in the list, 110it is inserted with the given 111.Ar value . 112If the variable does exist, the argument 113.Ar overwrite 114is tested; if 115.Ar overwrite is 116zero, the 117variable is not reset, otherwise it is reset 118to the given 119.Ar value . 120.Pp 121The 122.Fn putenv 123function takes an argument of the form ``name=value'' and is 124equivalent to: 125.Bd -literal -offset indent 126setenv(name, value, 1); 127.Ed 128.Pp 129The 130.Fn unsetenv 131function 132deletes all instances of the variable name pointed to by 133.Fa name 134from the list. 135.Sh RETURN VALUES 136The functions 137.Fn getenv_r , 138.Fn setenv , 139.Fn putenv , 140and 141.Fn unsetenv 142return zero if successful; otherwise the global variable 143.Va errno 144is set to indicate the error and a 145\-1 is returned. 146.Pp 147If 148.Fn getenv 149is successful, the string returned should be considered read-only. 150.Sh ERRORS 151.Bl -tag -width Er 152.It Bq Er EINVAL 153The 154.Fa name 155argument to 156.Fn unsetenv 157is a null pointer, points to an empty string, or points to a string 158containing an 159.Dq Li \&= 160character. 161.It Bq Er ENOMEM 162The function 163.Fn setenv 164or 165.Fn putenv 166failed because they were unable to allocate memory for the environment. 167.El 168The function 169.Fn getenv_r 170can return the following errors: 171.Bl -tag -width Er 172.It Bq Er ENOENT 173The variable 174.Fa name 175was not found in the environment. 176.It Bq Er ERANGE 177The value of the named variable is too long to fit in the supplied buffer. 178.El 179.Sh SEE ALSO 180.Xr csh 1 , 181.Xr sh 1 , 182.Xr execve 2 , 183.Xr environ 7 184.Sh STANDARDS 185The 186.Fn getenv 187function conforms to 188.St -ansiC . 189The 190.Fn putenv 191function conforms to 192.St -xpg4 . 193The 194.Fn unsetenv 195function conforms to 196.St -p1003.1-2001 . 197.Sh HISTORY 198The functions 199.Fn setenv 200and 201.Fn unsetenv 202appeared in 203.At v7 . 204The 205.Fn putenv 206function appeared in 207.Bx 4.3 Reno . 208