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