mirror of https://github.com/GnoConsortium/gno.git
219 lines
6.4 KiB
Groff
219 lines
6.4 KiB
Groff
.\" 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 <stdlib.h>
|
|
.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)
|