MirBSD manpage: getenv(3), putenv(3), setenv(3), unsetenv(3)

GETENV(3)                  BSD Programmer's Manual                   GETENV(3)

NAME

     getenv, putenv, setenv, unsetenv - environment variable functions

SYNOPSIS

     #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);

DESCRIPTION

     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.

RETURN VALUES

     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.

ERRORS

     [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.

SEE ALSO

     csh(1), sh(1), execve(2), issetugid(2), environ(7)

STANDARDS

     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.

HISTORY

     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.

CAVEATS

     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

Generated on 2021-12-07 11:07:08 by $MirOS: src/scripts/roff2htm,v 1.103 2021/01/23 20:24:35 tg Exp $ — This product includes material provided by mirabilos.

These manual pages and other documentation are copyrighted by their respective writers; their sources are available at the project’s CVSweb, AnonCVS and other mirrors. The rest is Copyright © 2002–2021 MirBSD.

This manual page’s HTML representation is supposed to be valid XHTML/1.1; if not, please send a bug report — diffs preferred.