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