mirror of
https://github.com/GnoConsortium/gno.git
synced 2024-12-22 14:30:29 +00:00
eb014e0fc2
Fixed some formatting so that it looks right on the GS (use .IP instead of .TP commands).
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)
|