GETENV(3) BSD Programmer's Manual GETENV(3)
getenv, putenv, setenv, unsetenv - environment variable functions
#include <stdlib.h>
char *
getenv(const char *name);
int
setenv(const char *name, const char *value, int overwrite);
int
putenv(char *string);
int
unsetenv(const char *name);
These functions set, unset, and fetch environment variables from the host
environment list.
The getenv() function obtains the current value of the environment vari-
able name (its first instance, if set multiple times). If the variable
name is not in the current environment, a NULL pointer is returned.
The setenv() function inserts or resets the environment variable name in
the current environment list. If the variable name does not exist in the
list, it is inserted with the given value. If the variable does exist,
the argument overwrite is tested; if overwrite is zero, the variable is
not reset, otherwise all previous occurrences of the name are first
deleted from the environment so the variable is reset to the given value.
The putenv() function takes an argument of the form name=value. The
memory pointed to by string becomes part of the environment and must not
be deallocated by the caller. If the variable already exists, it will be
overwritten. A common source of bugs is to pass a string argument that is
a locally scoped string buffer, which will result in corruption of the
environment after leaving the scope in which the variable is defined. For
this reason, the setenv() function is preferred over putenv().
The unsetenv() function deletes all instances of the variable name from
the list.
The putenv(), setenv() and unsetenv() functions return the value 0 if
successful; otherwise the value -1 is returned and the global variable
errno is set to indicate the error.
The getenv() function returns a pointer to the requested value, or NULL
if it could not be found. If getenv() is successful, the string returned
should be considered read-only.
[EINVAL] The getenv(), setenv() or unsetenv() functions were passed
a NULL or empty name or one containing an '=' character.
The putenv() function was passed a NULL pointer or a string
that did not contain an '=' character after at least one
other character (as name).
[ENOMEM] The setenv() or putenv() function failed because they were
unable to allocate memory for the environment.
csh(1), sh(1), execve(2), issetugid(2), environ(7)
The getenv() function conforms to ANSI X3.159-1989 ("ANSI C89"). Setting
errno to 0 on success, nonzero on error, is a MirBSD extension.
The putenv(), setenv(), and unsetenv() functions conform to IEEE Std
1003.1-2008 ("POSIX.1"). Handling an on-stack putenv() string argument
(strdup plus diagnostic in syslog) is a MirBSD extension.
The function getenv() appeared in Version 7 AT&T UNIX and 3BSD. The func-
tions setenv() and unsetenv() appeared in 4.3BSD-Tahoe. The putenv()
function appeared in 4.3BSD-Reno.
Before MirBSD #11, the arguments to setenv() could start and/or end with
an equals sign ('=') that was ignored for compatibility with legacy
operating systems. The current version features several more checks for
compliance with latest standards.
Before MirBSD #11, putenv() added a copy of string to the environment.
This has to be changed for POSIX compliance; this change may surprise.
Library code must be careful about using getenv() to read untrusted en-
vironment variables in setuid programs. The issetugid() function is pro-
vided for this purpose.
Whether only the first, last, any or all instances of an environment
variable whose name occurs multiple times in the environment are acted on
(returned, deleted, set) is implementation-specific. In MirBSD, it was
originally intended for the last match to be normative, for consistency
with both the shell and other usual duplicate resolution algorithms,
which did not only fail due to breakage in external code, but other
operating systems, the environment directive in sshd(8) authorised_keys
files, etc. all chose first match for environment variables, so this is
what is being converged on (including in mksh(1)). Setting an environment
variable multiple times by direct environ manipulation is discouraged.
MirBSD #10-current October 7, 2021 1