ENVIRON(7)

NAME
environ - user environment

SYNOPSIS
#include <stdlib.h>

extern char **environ;

DESCRIPTION
Under UNIX, an array of strings called the `environment' is made available by execve(2) when a process begins. By convention these strings have the form name=value. However, because of the shell variable and environment passing mechanisms normally provided for the IIgs (and with GNO and ORCA in particular), this method of controlling and accessing the environment has not previously been available. Specifically, under GNO and ORCA environ is not initialized by the exec(3) family of calls. To accomodate this 'feature', the library call environInit(3) has been provided to properly initialize environ.

The following names are used by various commands:

    PATH
        The sequence of directory prefixes that gsh(1), sh(1), time(1V), nice(1), etc., apply in searching for a file known by an incomplete path name. The prefixes are delimited by spaces since colons are valid pathname characters under GS/OS. Current versions of gsh parse PATH backwards, that is from back to front. lenviron has been compiled to match this behavior, but can be easily recompiled to conform to the more usual parsing method, front to back. See the lenviron distribution README file for more information.

    HOME
        The name of the user's login directory, set by login(1) from the password file /etc/passwd (see passwd(5)).

    TERM
        The type of terminal on which the user is logged in. This information is used by commands, such as nroff(1) or plot(1G), which may exploit special terminal capabilities. See /etc/termcap (termcap(5)) for a list of terminal types.

    SHELL
        The path name of the user's login shell.

    TERMCAP
        The string describing the terminal in TERM, or the name of the termcap file, see termcap(3), termcap(5).

    EXINIT
        A startup list of commands read by ex(1), edit, and vi(1).

    USER or LOGNAME
        The user's login name.

    TZ  The name of the time zone that the user is located in. If TZ is not present in the environment, the system's default time zone, normally the time zone that the computer is located in, is used.

Further names may be placed in the environment by the set and setenv commands under gsh(1), the export command and name=value arguments in sh(1), or by the setenv command if you use csh(1). It is unwise to conflict with certain sh(1) variables that are frequently exported by .profile files: MAIL, PS1, PS2, IFS.

Various names are expected to be defined and used by locale dependent commands and functions (see locale(5)).

GNO IMPLEMENTATION
The GNO implementation of the environment actually has two sets of shell variables. The first is the NULL-terminated array of strings pointed to by environ. The second is the set of internal shell variables set by such system calls as SetGS and UnsetVariableGS. The latter of these is the one normally used by ORCA/C. Unfortunately, the latter implementation makes the porting of some UNIX utilities more difficult. The environ library was created to solve this problem without adding significant overhead to environment calls when reference to environ is not needed.

When the environ variable is not needed, calls made to putenv(3), setenv(3), and getenv(3) result in only the internal shell variables to be set, and environ will remain NULL; its default value.

If, however, environ is to be accessed, then an initial call must be made to environInit(3). This produces the array of strings based on the shell variables defined internally, and keeps the array current with further calls to putenv(3), or setenv(3).

CAVEATS
Under the ORCA shell, three `extraneous' shell variables are defined: STATUS, Command, and Exit. These are reset with every call to the ORCA shell and should not, in general, be considered to be current.

When one of the exec(3) family of calls is carried out, the environment will not be passed on through environ. In order for the next process to use environ, it must make another call to environInit(3). Note, however, that child processes will still have residing in the internal shell variables all previous modifications to the environment.

In order to conduct an environment context switch, you must invoke the functions environPush(3) and environPop(3). This context switch behaves similarily to PushVariableGS or PopVariableGS, but will result in both internal and external shell variables being saved and restored, rather than just the internal variables.

While the environ array may be read by user applications, it cannot be directly modified with impudence; any additions or deletions to the environ array other that through the mentioned routines will not be reflected in the internal shell variables. 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.

FILES
/etc/passwd
/etc/termcap

HISTORY
This environ implementation was first made available in the (now deprecated) lenviron library. It was incorporated into libc as of GNO v2.0.6.

AUTHORS
The original environ library (and consequently portions of the current libc) was created for GNO and ORCA/Shell by Devin Reade. This implementation also contains code fragments from Dave Tribby and James Brookes.

The environ library also contains code is derived from software contributed to Berkeley by the American National Standards Committee X3, on Information Processing Systems. Those portions are copyright (c) 1988, 1991. The Regents of the University of California. All rights reserved.

SEE ALSO
gsh(1), execve(2), exec(3), execl(3), getenv(3), system(3), termcap(3), passwd(5), termcap(5)