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 13, 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 GNU-specific function, 85.Fn secure_getenv 86wraps the 87.Fn getenv 88function to prevent it from being run in "secure execution". 89Unlike in glibc, 90.Fn secure_getenv 91only checks if the 92.Fa setuid 93and 94.Fa setgid 95bits have been set or changed. 96These checks are subject to extension and change. 97.Pp 98The 99.Fn setenv 100function inserts or resets the environment variable 101.Fa name 102in the current environment list. 103If the variable 104.Fa name 105does not exist in the list, 106it is inserted with the given 107.Fa value . 108If the variable does exist, the argument 109.Fa overwrite 110is tested; if 111.Fa overwrite 112is zero, the 113variable is not reset, otherwise it is reset 114to the given 115.Fa value . 116.Pp 117The 118.Fn putenv 119function takes an argument of the form ``name=value'' and 120puts it directly into the current environment, 121so altering the argument shall change the environment. 122If the variable 123.Fa name 124does not exist in the list, 125it is inserted with the given 126.Fa value . 127If the variable 128.Fa name 129does exist, it is reset to the given 130.Fa value . 131.Pp 132The 133.Fn unsetenv 134function 135deletes all instances of the variable name pointed to by 136.Fa name 137from the list. 138.Pp 139If corruption (e.g., a name without a value) is detected while making a copy of 140environ for internal usage, then 141.Fn setenv , 142.Fn unsetenv 143and 144.Fn putenv 145will output a warning to stderr about the issue, drop the corrupt entry and 146complete the task without error. 147.Sh RETURN VALUES 148The 149.Fn getenv 150function returns the value of the environment variable as a 151.Dv NUL Ns 152-terminated string. 153If the variable 154.Fa name 155is not in the current environment, 156.Dv NULL 157is returned. 158.Pp 159The 160.Fn secure_getenv 161function returns 162.Dv NULL 163if the process is in "secure execution," otherwise it will call 164.Fn getenv . 165.Pp 166.Rv -std clearenv setenv putenv unsetenv 167.Sh ERRORS 168.Bl -tag -width Er 169.It Bq Er EINVAL 170The function 171.Fn getenv , 172.Fn setenv 173or 174.Fn unsetenv 175failed because the 176.Fa name 177is a 178.Dv NULL 179pointer, points to an empty string, or points to a string containing an 180.Dq Li \&= 181character. 182.Pp 183The function 184.Fn putenv 185failed because 186.Fa string 187is a 188.Dv NULL 189pointer, 190.Fa string 191is without an 192.Dq Li \&= 193character or 194.Dq Li \&= 195is the first character in 196.Fa string . 197This does not follow the 198.Tn POSIX 199specification. 200.It Bq Er ENOMEM 201The function 202.Fn setenv , 203.Fn unsetenv 204or 205.Fn putenv 206failed because they were unable to allocate memory for the environment. 207.El 208.Sh SEE ALSO 209.Xr csh 1 , 210.Xr sh 1 , 211.Xr execve 2 , 212.Xr environ 7 213.Sh STANDARDS 214The 215.Fn getenv 216function conforms to 217.St -isoC . 218The 219.Fn setenv , 220.Fn putenv 221and 222.Fn unsetenv 223functions conforms to 224.St -p1003.1-2001 . 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 252was added in 253.Fx 14 . 254.Sh BUGS 255Successive calls to 256.Fn setenv 257that assign a larger-sized 258.Fa value 259than any previous value to the same 260.Fa name 261will result in a memory leak. 262The 263.Fx 264semantics for this function 265(namely, that the contents of 266.Fa value 267are copied and that old values remain accessible indefinitely) make this 268bug unavoidable. 269Future versions may eliminate one or both of these 270semantic guarantees in order to fix the bug. 271