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.Dd March 14, 2023 33.Dt GETENV 3 34.Os 35.Sh NAME 36.Nm clearenv , 37.Nm getenv , 38.Nm putenv , 39.Nm secure_getenv , 40.Nm setenv , 41.Nm unsetenv 42.Nd environment variable functions 43.Sh LIBRARY 44.Lb libc 45.Sh SYNOPSIS 46.In stdlib.h 47.Ft int 48.Fn clearenv "void" 49.Ft char * 50.Fn getenv "const char *name" 51.Ft char * 52.Fn secure_getenv "const char *name" 53.Ft int 54.Fn setenv "const char *name" "const char *value" "int overwrite" 55.Ft int 56.Fn putenv "char *string" 57.Ft int 58.Fn unsetenv "const char *name" 59.Sh DESCRIPTION 60These functions set, unset and fetch environment variables from the 61host 62.Em environment list . 63.Pp 64The 65.Fn clearenv 66function clears all environment variables. 67New variables can be added using 68.Fn setenv 69and 70.Fn putenv . 71.Pp 72The 73.Fn getenv 74function obtains the current value of the environment variable, 75.Fa name . 76The application should not modify the string pointed 77to by the 78.Fn getenv 79function. 80.Pp 81The 82.Fn secure_getenv 83returns 84.Va NULL 85when the environment cannot be trusted, otherwise it acts like 86.Fn getenv . 87The environment currently is not trusted when 88.Xr issetugid 3 89returns a non-zero value, but other conditions may be added 90in the future. 91.Pp 92The 93.Fn setenv 94function inserts or resets the environment variable 95.Fa name 96in the current environment list. 97If the variable 98.Fa name 99does not exist in the list, 100it is inserted with the given 101.Fa value . 102If the variable does exist, the argument 103.Fa overwrite 104is tested; if 105.Fa overwrite 106is zero, the 107variable is not reset, otherwise it is reset 108to the given 109.Fa value . 110.Pp 111The 112.Fn putenv 113function takes an argument of the form ``name=value'' and 114puts it directly into the current environment, 115so altering the argument shall change the environment. 116If the variable 117.Fa name 118does not exist in the list, 119it is inserted with the given 120.Fa value . 121If the variable 122.Fa name 123does exist, it is reset to the given 124.Fa value . 125.Pp 126The 127.Fn unsetenv 128function 129deletes all instances of the variable name pointed to by 130.Fa name 131from the list. 132.Pp 133If corruption (e.g., a name without a value) is detected while making a copy of 134environ for internal usage, then 135.Fn setenv , 136.Fn unsetenv 137and 138.Fn putenv 139will output a warning to stderr about the issue, drop the corrupt entry and 140complete the task without error. 141.Sh RETURN VALUES 142The 143.Fn getenv 144function returns the value of the environment variable as a 145.Dv NUL Ns 146-terminated string. 147If the variable 148.Fa name 149is not in the current environment, 150.Dv NULL 151is returned. 152.Pp 153The 154.Fn secure_getenv 155function returns 156.Dv NULL 157if the process is in "secure execution," otherwise it will call 158.Fn getenv . 159.Pp 160.Rv -std clearenv setenv putenv unsetenv 161.Sh ERRORS 162.Bl -tag -width Er 163.It Bq Er EINVAL 164The function 165.Fn getenv , 166.Fn setenv 167or 168.Fn unsetenv 169failed because the 170.Fa name 171is a 172.Dv NULL 173pointer, points to an empty string, or points to a string containing an 174.Dq Li \&= 175character. 176.Pp 177The function 178.Fn putenv 179failed because 180.Fa string 181is a 182.Dv NULL 183pointer, 184.Fa string 185is without an 186.Dq Li \&= 187character or 188.Dq Li \&= 189is the first character in 190.Fa string . 191This does not follow the 192.Tn POSIX 193specification. 194.It Bq Er ENOMEM 195The function 196.Fn setenv , 197.Fn unsetenv 198or 199.Fn putenv 200failed because they were unable to allocate memory for the environment. 201.El 202.Sh SEE ALSO 203.Xr csh 1 , 204.Xr sh 1 , 205.Xr execve 2 , 206.Xr environ 7 207.Sh STANDARDS 208The 209.Fn getenv 210function conforms to 211.St -isoC . 212The 213.Fn setenv , 214.Fn putenv 215and 216.Fn unsetenv 217functions conforms to 218.St -p1003.1-2001 . 219The 220.Fn secure_getenv 221function is expected to be glibc-compatible. 222.Sh HISTORY 223The functions 224.Fn setenv 225and 226.Fn unsetenv 227appeared in 228.At v7 . 229The 230.Fn putenv 231function appeared in 232.Bx 4.3 Reno . 233.Pp 234Until 235.Fx 7.0 , 236.Fn putenv 237would make a copy of 238.Fa string 239and insert it into the environment using 240.Fn setenv . 241This was changed to use 242.Fa string 243as the memory location of the ``name=value'' pair to follow the 244.Tn POSIX 245specification. 246.Pp 247The 248.Fn clearenv 249and 250.Fn secure_getenv 251functions were added in 252.Fx 14 . 253.Sh BUGS 254Successive calls to 255.Fn setenv 256that assign a larger-sized 257.Fa value 258than any previous value to the same 259.Fa name 260will result in a memory leak. 261The 262.Fx 263semantics for this function 264(namely, that the contents of 265.Fa value 266are copied and that old values remain accessible indefinitely) make this 267bug unavoidable. 268Future versions may eliminate one or both of these 269semantic guarantees in order to fix the bug. 270