diff options
Diffstat (limited to 'lib/libc/stdlib/getenv.3')
-rw-r--r-- | lib/libc/stdlib/getenv.3 | 70 |
1 files changed, 63 insertions, 7 deletions
diff --git a/lib/libc/stdlib/getenv.3 b/lib/libc/stdlib/getenv.3 index 5566d7b01dcd..045a1831dfdc 100644 --- a/lib/libc/stdlib/getenv.3 +++ b/lib/libc/stdlib/getenv.3 @@ -29,16 +29,15 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.\" @(#)getenv.3 8.2 (Berkeley) 12/11/93 -.\" $FreeBSD$ -.\" -.Dd November 7, 2021 +.Dd April 22, 2025 .Dt GETENV 3 .Os .Sh NAME .Nm clearenv , .Nm getenv , +.Nm getenv_r , .Nm putenv , +.Nm secure_getenv , .Nm setenv , .Nm unsetenv .Nd environment variable functions @@ -51,6 +50,10 @@ .Ft char * .Fn getenv "const char *name" .Ft int +.Fn getenv_r "const char *name" "char *buf" "size_t len" +.Ft char * +.Fn secure_getenv "const char *name" +.Ft int .Fn setenv "const char *name" "const char *value" "int overwrite" .Ft int .Fn putenv "char *string" @@ -71,7 +74,8 @@ and .Pp The .Fn getenv -function obtains the current value of the environment variable, +function obtains the current value of the environment variable +designated by .Fa name . The application should not modify the string pointed to by the @@ -79,6 +83,27 @@ to by the function. .Pp The +.Fn getenv_r +function obtains the current value of the environment variable +designated by +.Fa name +and copies it into the buffer +.Fa buf +of length +.Fa len . +.Pp +The +.Fn secure_getenv +returns +.Va NULL +when the environment cannot be trusted, otherwise it acts like +.Fn getenv . +The environment currently is not trusted when +.Xr issetugid 2 +returns a non-zero value, but other conditions may be added +in the future. +.Pp +The .Fn setenv function inserts or resets the environment variable .Fa name @@ -139,12 +164,20 @@ is not in the current environment, .Dv NULL is returned. .Pp -.Rv -std clearenv setenv putenv unsetenv +The +.Fn secure_getenv +function returns +.Dv NULL +if the process is in "secure execution," otherwise it will call +.Fn getenv . +.Pp +.Rv -std clearenv getenv_r setenv putenv unsetenv .Sh ERRORS .Bl -tag -width Er .It Bq Er EINVAL The function .Fn getenv , +.Fn getenv_r , .Fn setenv or .Fn unsetenv @@ -173,6 +206,11 @@ is the first character in This does not follow the .Tn POSIX specification. +.It Bq Er ENOENT +The function +.Fn getenv_r +failed because the requested variable was not found in the +environment. .It Bq Er ENOMEM The function .Fn setenv , @@ -180,6 +218,11 @@ The function or .Fn putenv failed because they were unable to allocate memory for the environment. +.It Bq Er ERANGE +The function +.Fn getenv_r +failed because the value of the requested variable was too long to fit +in the provided buffer. .El .Sh SEE ALSO .Xr csh 1 , @@ -198,6 +241,10 @@ and .Fn unsetenv functions conforms to .St -p1003.1-2001 . +The +.Fn secure_getenv +function conforms to +.St -p1003.1-2024 . .Sh HISTORY The functions .Fn setenv @@ -225,8 +272,17 @@ specification. .Pp The .Fn clearenv -was added in +and +.Fn secure_getenv +functions were added in .Fx 14 . +.Pp +The +.Fn getenv_r +function first appeared in +.Nx 4.0 +and was added in +.Fx 15 . .Sh BUGS Successive calls to .Fn setenv |