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