GETENV(3)

NAME

getenv, putenv, setenv, unsetenv, environInit, environPop, environPush, - environment variable functions

SYNOPSIS
#include <stdlib.h>

char *getenv (const char *name);
int putenv (const char *string);
int setenv (const char *name, const char *value int overwrite);
void unsetenv (const char *name);

int environInit (void);
int environPush (void);
void environPop (void);

DESCRIPTION
These functions set, unset and fetch environment variables from the host environment list. For compatibility with differing environment conventions, the given arguments name and value may be appended and prepended, respectively, 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 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 performs the equivalent of:
	setenv(name, value, 1);
and expects string to be of the form name=value.

The unsetenv function deletes all instances of the variable name pointed to by name from the list.

The environInit, environPush, and environPop functions are non-standard (GNO-specific).

The environInit function is used to initialize the environ variable, since this functionality is provided by neither shell. It is necessary to use environInit before any explicit references to environ, but if environ is not to be referenced, it is not necessary to call environInit at all.

environPush and environPop are used to push and pop, respectively, the environment stack. See environ (8) for more information.

RETURN VALUES
The functions environInit, environPush, putenv, and setenv return zero if successful; otherwise the global variable errno is set to indicate the error and a -1 is returned.

ERRORS

ENOMEM
    The functions environInit, environPush, putenv, or setenv failed because they were unable to allocate memory for the environment.

CAVEATS
If environ has been modified without using the library routines, then the internal shell variables and the shell environment represented by environ will not be consistent. Also, since environ entries are dynamically allocated and freed, modifying those entries without using the library routines may result in memory trashing and unpredicable behavior.

AUTHORS
These routines were written for GNO primarily by Devin Reade. They also contain code fragments from Dave Tribby and James Brookes.

These routines also contains code is derived from software contributed to Berkeley by the American National Standards Committee X3, on Information Processing Systems.

SEE ALSO
gsh(1), sh(1), execve(2), environ(7),

HISTORY
The functions setenv and unsetenv appeared in Version 7 AT&T UNIX. The putenv function appeared in 4.3BSD (Reno).

The first appearance of these routines for GNO was as part of the (now superceeded) lenviron library. They were formally incorporated into GNO as of v2.0.6. These routines are no longer guaranteed to be compatible with the ORCA/Shell.

The functions environInit, environPush, and environPop were previously initenv, pushenv, and popenv, respectively.