NAME
getenv,
getenv_r,
putenv,
setenv,
unsetenv —
environment variable functions
LIBRARY
Standard C Library (libc, -lc)
SYNOPSIS
#include <stdlib.h>
char *
getenv(
const char
*name);
int
getenv_r(
const
char *name,
char
*buf,
size_t len);
int
setenv(
const char
*name,
const char
*value,
int
overwrite);
int
putenv(
char
*string);
int
unsetenv(
const
char *name);
DESCRIPTION
These functions set, unset and fetch environment variables from the host
environment list. For compatibility with differing
environment conventions, the
getenv() or
getenv_r() given argument
name may be
appended with an equal sign “
=
”.
The
getenv() function obtains the current value of the
environment variable
name. If the variable
name is not in the current environment, a
NULL
pointer is returned.
The
getenv_r() function obtains the current value of the
environment variable
name and copies it to
buf. If
name is not in the current
environment, or the string length of the value of
name
is longer than
len characters, then -1 is returned and
errno is set to indicate the error.
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
it is reset to the given
value.
The
putenv() function takes an argument of the form
“name=value” and it will set the environment variable
“name” equal to “value” by altering an existing entry,
or creating a new one if an existing one does not exist. The actual string
argument passed to
putenv() will become part of the
environment. If one changes the string, the environment will also change.
The
unsetenv() function deletes all instances of the variable
name pointed to by
name from the list.
RETURN VALUES
The functions
getenv_r(),
setenv(),
putenv(), and
unsetenv() return zero if
successful; otherwise the global variable
errno is set
to indicate the error and a -1 is returned.
If
getenv() is successful, the string returned should be
considered read-only.
ERRORS
-
-
- [
EINVAL
]
- The name argument to
setenv() or unsetenv() is a null
pointer, points to an empty string, or points to a string containing an
“
=
” character. The
value argument to setenv() is a
null pointer. The string argument to
putenv() is a null pointer, or points to a string that
either starts with a “=
” character or
does not contain one at all.
-
-
- [
ENOMEM
]
- The function setenv() or
putenv() failed because they were unable to allocate
memory for the environment.
The function
getenv_r() can return the following errors:
-
-
- [
ENOENT
]
- The variable name was not found in
the environment.
-
-
- [
ERANGE
]
- The value of the named variable is too long to fit in the
supplied buffer.
SEE ALSO
csh(1),
sh(1),
execve(2),
environ(7)
STANDARDS
The
getenv() function conforms to
ANSI
X3.159-1989 (“ANSI C89”). The
putenv() function conforms to
X/Open
Portability Guide Issue 4 (“XPG4”). The
unsetenv() function conforms to
IEEE Std
1003.1-2001 (“POSIX.1”).
HISTORY
The functions
setenv() and
unsetenv()
appeared in
Version 7 AT&T UNIX. The
putenv() function appeared in
4.3BSD-Reno.