ENVIRON(7)                       Miscellaneous                      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 avail-
       able 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 char-
                     acters  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 recom-
                     piled 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 capabili-
                     ties.  See /etc/termcap (termcap(5)) for a list of termi-
                     nal 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 com-
                     puter 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 vari-
       ables set by such system calls as SetGS and UnsetVariableGS.  The  lat-
       ter  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 with-
       out 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 unpredica-
       ble behavior.


FILES

       /etc/passwd
       /etc/termcap


HISTORY

       This environ implementation was first made available in the (now depre-
       cated)  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 imple-
       mentation 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)



GNO                              15 April 1998                      ENVIRON(7)

Man(1) output converted with man2html