1.\" $NetBSD: getenv.3,v 1.25 2010/10/26 22:34:33 wiz Exp $ 2.\" 3.\" Copyright (c) 1988, 1991, 1993 4.\" The Regents of the University of California. All rights reserved. 5.\" 6.\" This code is derived from software contributed to Berkeley by 7.\" the American National Standards Committee X3, on Information 8.\" Processing Systems. 9.\" 10.\" Redistribution and use in source and binary forms, with or without 11.\" modification, are permitted provided that the following conditions 12.\" are met: 13.\" 1. Redistributions of source code must retain the above copyright 14.\" notice, this list of conditions and the following disclaimer. 15.\" 2. Redistributions in binary form must reproduce the above copyright 16.\" notice, this list of conditions and the following disclaimer in the 17.\" documentation and/or other materials provided with the distribution. 18.\" 3. Neither the name of the University nor the names of its contributors 19.\" may be used to endorse or promote products derived from this software 20.\" without specific prior written permission. 21.\" 22.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 23.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 24.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 25.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 26.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 27.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 28.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 29.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 30.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 31.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 32.\" SUCH DAMAGE. 33.\" 34.\" from: @(#)getenv.3 8.2 (Berkeley) 12/11/93 35.\" 36.Dd October 25, 2010 37.Dt GETENV 3 38.Os 39.Sh NAME 40.Nm getenv , 41.Nm getenv_r , 42.Nm putenv , 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 char * 51.Fn getenv "const char *name" 52.Ft int 53.Fn getenv_r "const char *name" "char *buf" "size_t len" 54.Ft int 55.Fn setenv "const char *name" "const char *value" "int overwrite" 56.Ft int 57.Fn putenv "char *string" 58.Ft int 59.Fn unsetenv "const char *name" 60.Sh DESCRIPTION 61These functions set, unset and fetch environment variables from the 62host 63.Em environment list . 64For compatibility with differing environment conventions, 65the 66.Fn getenv 67or 68.Fn getenv_r 69given argument 70.Ar name 71may be appended with an equal sign 72.Dq Li \&= . 73.Pp 74The 75.Fn getenv 76function obtains the current value of the environment variable 77.Ar name . 78If the variable 79.Ar name 80is not in the current environment, a 81.Dv NULL 82pointer is returned. 83.Pp 84The 85.Fn getenv_r 86function obtains the current value of the environment variable 87.Fa name 88and copies it to 89.Fa buf . 90If 91.Fa name 92is not in the current environment, or the string length of the value of 93.Fa name 94is longer than 95.Fa len 96characters, then \-1 is returned and 97.Va errno 98is set to indicate the error. 99.Pp 100The 101.Fn setenv 102function inserts or resets the environment variable 103.Ar name 104in the current environment list. 105If the variable 106.Ar name 107does not exist in the list, 108it is inserted with the given 109.Ar value . 110If the variable does exist, the argument 111.Ar overwrite 112is tested; if 113.Ar overwrite is 114zero, the 115variable is not reset, otherwise it is reset 116to the given 117.Ar value . 118.Pp 119The 120.Fn putenv 121function takes an argument of the form 122.Dq name=value 123and it will set the environment variable 124.Dq name 125equal to 126.Dq value 127by altering an existing entry, or creating a new one if an existing 128one does not exist. 129The actual string argument passed to 130.Fn putenv 131will become part of the environment. 132If one changes the string, the environment will also change. 133.Pp 134The 135.Fn unsetenv 136function 137deletes all instances of the variable name pointed to by 138.Fa name 139from the list. 140.Sh RETURN VALUES 141The functions 142.Fn getenv_r , 143.Fn setenv , 144.Fn putenv , 145and 146.Fn unsetenv 147return zero if successful; otherwise the global variable 148.Va errno 149is set to indicate the error and a 150\-1 is returned. 151.Pp 152If 153.Fn getenv 154is successful, the string returned should be considered read-only. 155.Sh ERRORS 156.Bl -tag -width Er 157.It Bq Er EINVAL 158The 159.Fa name 160argument to 161.Fn setenv 162or 163.Fn unsetenv 164is a null pointer, points to an empty string, or points to a string 165containing an 166.Dq Li \&= 167character. 168The 169.Fa value 170argument to 171.Fn setenv 172is a null pointer. 173The 174.Fa string 175argument to 176.Fn putenv 177is a null pointer, or points to a string that either starts with a 178.Dq Li \&= 179character or does not contain one at all. 180.It Bq Er ENOMEM 181The function 182.Fn setenv 183or 184.Fn putenv 185failed because they were unable to allocate memory for the environment. 186.El 187.Pp 188The function 189.Fn getenv_r 190can return the following errors: 191.Bl -tag -width Er 192.It Bq Er ENOENT 193The variable 194.Fa name 195was not found in the environment. 196.It Bq Er ERANGE 197The value of the named variable is too long to fit in the supplied buffer. 198.El 199.Sh SEE ALSO 200.Xr csh 1 , 201.Xr sh 1 , 202.Xr execve 2 , 203.Xr environ 7 204.Sh STANDARDS 205The 206.Fn getenv 207function conforms to 208.St -ansiC . 209The 210.Fn putenv 211function conforms to 212.St -xpg4 . 213The 214.Fn unsetenv 215function conforms to 216.St -p1003.1-2001 . 217.Sh HISTORY 218The functions 219.Fn setenv 220and 221.Fn unsetenv 222appeared in 223.At v7 . 224The 225.Fn putenv 226function appeared in 227.Bx 4.3 Reno . 228