aboutsummaryrefslogtreecommitdiff
path: root/lib/libc/stdlib/getenv.3
diff options
context:
space:
mode:
Diffstat (limited to 'lib/libc/stdlib/getenv.3')
-rw-r--r--lib/libc/stdlib/getenv.370
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