.\" This man page has been written to conform with the lenviron v1.1.3 .\" release for Gno v2.0.3 and later by Devin Reade. glyn@cs.ualberta.ca .\" .TH ENVIRON 7 "15 April 1998" GNO "Miscellaneous" .SH NAME environ \- user environment .SH SYNOPSIS #include .LP .B "extern char **environ;" .SH DESCRIPTION Under UNIX, an array of strings called the `environment' is made available by .BR execve (2) when a process begins. By convention these strings have the form \fIname=value\fR. 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 .BR environ is not initialized by the .BR exec (3) family of calls. To accomodate this \'feature\', the library call .BR environInit (3) has been provided to properly initialize .BR environ . .LP The following names are used by various commands: .RS .IP \fBPATH\fR The sequence of directory prefixes that .BR gsh (1), .BR sh (1), .BR time (1V), .BR 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 .B gsh parse .B PATH backwards, that is from back to front. .B 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 .B lenviron distribution README file for more information. .IP \fBHOME\fR The name of the user's login directory, set by .BR login (1) from the password file .B /etc/passwd (see .BR passwd (5)). .IP \fBTERM\fR The type of terminal on which the user is logged in. This information is used by commands, such as .BR nroff (1) or .BR plot (1G), which may exploit special terminal capabilities. See .B /etc/termcap .RB ( termcap (5)) for a list of terminal types. .IP \fBSHELL\fR The path name of the user's login shell. .IP \fBTERMCAP\fR The string describing the terminal in .SM TERM, or the name of the .B termcap file, see .BR termcap (3), .BR termcap (5). .IP \fBEXINIT\fR A startup list of commands read by .BR ex (1), .BR edit , and .BR vi (1). .IP "\fBUSER\fR or \fBLOGNAME\fR" The user's login name. .IP \fBTZ\fR The name of the time zone that the user is located in. If .B 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. .RE .LP Further names may be placed in the environment by the .IR set " and " setenv commands under .BR gsh (1), the .I export command and .IR name = value arguments in .BR sh (1), or by the .B setenv command if you use .BR csh (1). It is unwise to conflict with certain .BR sh (1) variables that are frequently exported by .B .profile files: .BR \s-1MAIL\s0 , .BR \s-1PS\s01 , .BR \s-1PS\s02 , .BR \s-1IFS\s0 . .LP Various names are expected to be defined and used by locale dependent commands and functions (see .BR locale (5)). .SH 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 .BR environ . The second is the set of internal shell variables set by such system calls as .BR 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 .BR environ library was created to solve this problem without adding significant overhead to environment calls when reference to .BR environ is not needed. .LP When the .BR environ variable is not needed, calls made to .BR putenv (3), .BR setenv "(3), and" .BR getenv (3) result in only the internal shell variables to be set, and .BR environ will remain NULL; its default value. .LP If, however, .BR environ is to be accessed, then an initial call must be made to .BR environInit (3). This produces the array of strings based on the shell variables defined internally, and keeps the array current with further calls to .BR putenv "(3), or" .BR setenv (3). .SH CAVEATS Under the ORCA shell, three `extraneous' shell variables are defined: .BR STATUS , .BR Command ", and" .BR Exit . These are reset with every call to the ORCA shell and should not, in general, be considered to be current. .LP When one of the .BR exec (3) family of calls is carried out, the environment will not be passed on through .BR environ . In order for the next process to use .BR environ , it must make another call to .BR environInit (3). Note, however, that child processes will still have residing in the internal shell variables all previous modifications to the environment. .LP In order to conduct an environment context switch, you must invoke the functions .BR environPush (3) and .BR environPop (3). This context switch behaves similarily to .BR PushVariableGS " or " PopVariableGS , but will result in both internal and external shell variables being saved and restored, rather than just the internal variables. .LP While the .BR environ array may be read by user applications, it cannot be directly modified with impudence; any additions or deletions to the .BR 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. .SH FILES /etc/passwd .br /etc/termcap .SH HISTORY This .BR environ implementation was first made available in the (now deprecated) .IR lenviron library. It was incorporated into .IR libc as of GNO v2.0.6. .SH 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. .LP 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. .SH SEE ALSO .BR gsh (1), .BR execve (2), .BR exec (3), .BR execl (3), .BR getenv (3), .BR system (3), .BR termcap (3), .BR passwd (5), .BR termcap (5)