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