| getenv.3 (169177) | getenv.3 (171195) |
|---|---|
| 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 --- 16 unchanged lines hidden (view full) --- 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 | 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 --- 16 unchanged lines hidden (view full) --- 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: head/lib/libc/stdlib/getenv.3 169177 2007-05-01 16:02:44Z ache $ | 33.\" $FreeBSD: head/lib/libc/stdlib/getenv.3 171195 2007-07-04 00:00:41Z scf $ |
| 34.\" | 34.\" |
| 35.Dd October 12, 2006 | 35.Dd June 20, 2007 |
| 36.Dt GETENV 3 37.Os 38.Sh NAME 39.Nm getenv , 40.Nm putenv , 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 char * 49.Fn getenv "const char *name" 50.Ft int 51.Fn setenv "const char *name" "const char *value" "int overwrite" 52.Ft int | 36.Dt GETENV 3 37.Os 38.Sh NAME 39.Nm getenv , 40.Nm putenv , 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 char * 49.Fn getenv "const char *name" 50.Ft int 51.Fn setenv "const char *name" "const char *value" "int overwrite" 52.Ft int |
| 53.Fn putenv "const char *string" 54.Ft void | 53.Fn putenv "char *string" 54.Ft int |
| 55.Fn unsetenv "const char *name" 56.Sh DESCRIPTION 57These functions set, unset and fetch environment variables from the 58host 59.Em environment list . | 55.Fn unsetenv "const char *name" 56.Sh DESCRIPTION 57These functions set, unset and fetch environment variables from the 58host 59.Em environment list . |
| 60For compatibility with differing environment conventions, 61the given arguments 62.Fa name 63and 64.Fa value 65may be appended and prepended, 66respectively, 67with an equal sign 68.Dq Li \&= . | |
| 69.Pp 70The 71.Fn getenv 72function obtains the current value of the environment variable, 73.Fa name . 74The application should not modify the string pointed 75to by the 76.Fn getenv --- 15 unchanged lines hidden (view full) --- 92.Fa overwrite 93is zero, the 94variable is not reset, otherwise it is reset 95to the given 96.Fa value . 97.Pp 98The 99.Fn putenv | 60.Pp 61The 62.Fn getenv 63function obtains the current value of the environment variable, 64.Fa name . 65The application should not modify the string pointed 66to by the 67.Fn getenv --- 15 unchanged lines hidden (view full) --- 83.Fa overwrite 84is zero, the 85variable is not reset, otherwise it is reset 86to the given 87.Fa value . 88.Pp 89The 90.Fn putenv |
| 100function takes an argument of the form ``name=value'' and is 101equivalent to: 102.Bd -literal -offset indent 103setenv(name, value, 1); 104.Ed | 91function takes an argument of the form ``name=value'' and 92puts it directly into the current environment, 93so altering the argument shall change the environment. 94If the variable 95.Fa name 96does not exist in the list, 97it is inserted with the given 98.Fa value . 99If the variable 100.Fa name 101does exist, it is reset to the given 102.Fa value . |
| 105.Pp 106The 107.Fn unsetenv 108function 109deletes all instances of the variable name pointed to by 110.Fa name 111from the list. 112.Sh RETURN VALUES 113The 114.Fn getenv 115function returns the value of the environment variable as a 116.Dv NUL Ns 117-terminated string. 118If the variable 119.Fa name 120is not in the current environment, 121.Dv NULL 122is returned. 123.Pp | 103.Pp 104The 105.Fn unsetenv 106function 107deletes all instances of the variable name pointed to by 108.Fa name 109from the list. 110.Sh RETURN VALUES 111The 112.Fn getenv 113function returns the value of the environment variable as a 114.Dv NUL Ns 115-terminated string. 116If the variable 117.Fa name 118is not in the current environment, 119.Dv NULL 120is returned. 121.Pp |
| 124.Rv -std setenv putenv | 122.Rv -std setenv putenv unsetenv |
| 125.Sh ERRORS 126.Bl -tag -width Er | 123.Sh ERRORS 124.Bl -tag -width Er |
| 127.It Bq Er ENOMEM | 125.It Bq Er EINVAL |
| 128The function | 126The function |
| 127.Fn getenv , |
|
| 129.Fn setenv 130or | 128.Fn setenv 129or |
| 130.Fn unsetenv 131failed because the 132.Fa name 133is a 134.Dv NULL 135pointer, points to an empty string, or points to a string containing an 136.Dq Li \&= 137character. 138.Pp 139The function |
|
| 131.Fn putenv | 140.Fn putenv |
| 141failed because 142.Fa string 143is a 144.Dv NULL 145pointer, 146.Fa string is without an 147.Dq Li \&= 148character or 149.Dq Li \&= 150is the first character in 151.Fa string . 152This does not follow the 153.Tn POSIX 154specification. 155.It Bq Er ENOMEM 156The function 157.Fn setenv , 158.Fn unsetenv 159or 160.Fn putenv |
|
| 132failed because they were unable to allocate memory for the environment. | 161failed because they were unable to allocate memory for the environment. |
| 162.It Bq Er EFAULT 163The functions 164.Fn setenv , 165.Fn unsetenv 166or 167.Fn putenv 168failed to make a valid copy of the environment due to the environment being 169corrupt (i.e., a name without a value). A warning will be output to stderr with 170information about the issue. |
|
| 133.El 134.Sh SEE ALSO 135.Xr csh 1 , 136.Xr sh 1 , 137.Xr execve 2 , 138.Xr environ 7 139.Sh STANDARDS 140The 141.Fn getenv 142function conforms to 143.St -isoC . | 171.El 172.Sh SEE ALSO 173.Xr csh 1 , 174.Xr sh 1 , 175.Xr execve 2 , 176.Xr environ 7 177.Sh STANDARDS 178The 179.Fn getenv 180function conforms to 181.St -isoC . |
| 182The 183.Fn setenv , 184.Fn putenv 185and 186.Fn unsetenv 187functions conforms to 188.St -p1003.1-2001 . |
|
| 144.Sh HISTORY 145The functions 146.Fn setenv 147and 148.Fn unsetenv 149appeared in 150.At v7 . 151The 152.Fn putenv 153function appeared in 154.Bx 4.3 Reno . | 189.Sh HISTORY 190The functions 191.Fn setenv 192and 193.Fn unsetenv 194appeared in 195.At v7 . 196The 197.Fn putenv 198function appeared in 199.Bx 4.3 Reno . |
| 200.Pp 201Until 202.Fx 7.0 , 203.Fn putenv 204would make a copy of 205.Fa string 206and insert it into the environment using 207.Fn setenv . 208This was changed to use 209.Fa string 210as the memory location of the ``name=value'' pair to follow the 211.Tn POSIX 212specification. |
|
| 155.Sh BUGS 156Successive calls to 157.Fn setenv | 213.Sh BUGS 214Successive calls to 215.Fn setenv |
| 158or 159.Fn putenv 160assigning a differently sized | 216that assign a larger-sized |
| 161.Fa value | 217.Fa value |
| 162to the same | 218than any previous value to the same |
| 163.Fa name 164will result in a memory leak. 165The 166.Fx | 219.Fa name 220will result in a memory leak. 221The 222.Fx |
| 167semantics for these functions | 223semantics for this function |
| 168(namely, that the contents of 169.Fa value 170are copied and that old values remain accessible indefinitely) make this 171bug unavoidable. 172Future versions may eliminate one or both of these 173semantic guarantees in order to fix the bug. | 224(namely, that the contents of 225.Fa value 226are copied and that old values remain accessible indefinitely) make this 227bug unavoidable. 228Future versions may eliminate one or both of these 229semantic guarantees in order to fix the bug. |