'\"
.\"  Copyright 1989 AT&T  Copyright (c) 2002, Sun Microsystems, Inc.  All Rights Reserved
.\" Copyright 2025 Oxide Computer Company
.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
.Dd January 19, 2025
.Dt GETENV 3C
.Os
.Sh NAME
.Nm getenv ,
.Nm secure_getenv
.Nd return value for environment name
.Sh LIBRARY
.Lb libc
.Sh SYNOPSIS
.In stdlib.h
.Ft "char *"
.Fo getenv
.Fa "const char *name"
.Fc
.Ft "char *"
.Fo secure_getenv
.Fa "const char *name"
.Fc
.Sh DESCRIPTION
The
.Fn getenv
function searches the environment list
.Po
see
.Xr environ 7
.Pc
for a string of the form
.Em name Ns = Ns Em Value
and, if the string is present, returns a pointer to the
.Em value
in the current environment.
.Pp
The
.Fn secure_getenv
function behaves similarly; however, evaluates the conditions that the
process was executed under.
If the process was executed in a way that it is considered setuid,
setgid, or raised its privileges, that is the
.Xr issetugid 2
function would return true, then the
.Fn secure_getenv
function will always return
.Dv NULL .
This is designed for programs that want to ensure they do not trust
potentially malicious user input while executed with elevated
capabilities.
In all other respects, the
.Fn secure_getenv
function is identical to the
.Fn getenv
function.
.Sh RETURN VALUES
If successful, the
.Fn getenv
and
.Fn secure_getenv
functions return a pointer to the
.Em value
in the current environment; otherwise, they returns a
.Dv NULL
pointer.
.Sh USAGE
The
.Fn getenv
function can be safely called from a multithreaded application.
Care must be exercised when using both
.Fn getenv
and
.Xr putenv 3C
in a multithreaded application.
These functions examine and modify the environment list, which is shared by all
threads in an application.
The system prevents the list from being accessed simultaneously by two different
threads.
It does not, however, prevent two threads from successively accessing the
environment list using
.Fn getenv
or
.Xr putenv 3C
.Sh INTERFACE STABILITY
.Sy Committed
.Sh MT-LEVEL
.Sy Safe
.Sh SEE ALSO
.Xr exec 2 ,
.Xr issetugid 2 ,
.Xr putenv 3C ,
.Xr attributes 7 ,
.Xr environ 7 ,
.Xr standards 7