mirror of
https://git.FreeBSD.org/src.git
synced 2024-12-11 09:50:12 +00:00
221 lines
8.9 KiB
Plaintext
221 lines
8.9 KiB
Plaintext
'\"
|
|
'\" Copyright (c) 1993 The Regents of the University of California.
|
|
'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
|
|
'\"
|
|
'\" See the file "license.terms" for information on usage and redistribution
|
|
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
|
|
'\"
|
|
'\" SCCS: @(#) tclvars.n 1.15 96/04/12 08:28:20
|
|
'\"
|
|
.so man.macros
|
|
.TH tclvars n 7.5 Tcl "Tcl Built-In Commands"
|
|
.BS
|
|
'\" Note: do not modify the .SH NAME line immediately below!
|
|
.SH NAME
|
|
tclvars \- Variables used by Tcl
|
|
.BE
|
|
|
|
.SH DESCRIPTION
|
|
.PP
|
|
The following global variables are created and managed automatically
|
|
by the Tcl library. Except where noted below, these variables should
|
|
normally be treated as read-only by application-specific code and by users.
|
|
.TP
|
|
\fBenv\fR
|
|
This variable is maintained by Tcl as an array
|
|
whose elements are the environment variables for the process.
|
|
Reading an element will return the value of the corresponding
|
|
environment variable.
|
|
Setting an element of the array will modify the corresponding
|
|
environment variable or create a new one if it doesn't already
|
|
exist.
|
|
Unsetting an element of \fBenv\fR will remove the corresponding
|
|
environment variable.
|
|
Changes to the \fBenv\fR array will affect the environment
|
|
passed to children by commands like \fBexec\fR.
|
|
If the entire \fBenv\fR array is unset then Tcl will stop
|
|
monitoring \fBenv\fR accesses and will not update environment
|
|
variables.
|
|
.TP
|
|
\fBerrorCode\fR
|
|
After an error has occurred, this variable will be set to hold
|
|
additional information about the error in a form that is easy
|
|
to process with programs.
|
|
\fBerrorCode\fR consists of a Tcl list with one or more elements.
|
|
The first element of the list identifies a general class of
|
|
errors, and determines the format of the rest of the list.
|
|
The following formats for \fBerrorCode\fR are used by the
|
|
Tcl core; individual applications may define additional formats.
|
|
.RS
|
|
.TP
|
|
\fBARITH\fI code msg\fR
|
|
.VS
|
|
This format is used when an arithmetic error occurs (e.g. an attempt
|
|
to divide by zero in the \fBexpr\fR command).
|
|
\fICode\fR identifies the precise error and \fImsg\fR provides a
|
|
human-readable description of the error. \fICode\fR will be either
|
|
DIVZERO (for an attempt to divide by zero),
|
|
DOMAIN (if an argument is outside the domain of a function, such as acos(\-3)),
|
|
IOVERFLOW (for integer overflow),
|
|
OVERFLOW (for a floating-point overflow),
|
|
or UNKNOWN (if the cause of the error cannot be determined).
|
|
.VE
|
|
.TP
|
|
\fBCHILDKILLED\fI pid sigName msg\fR
|
|
This format is used when a child process has been killed because of
|
|
a signal. The second element of \fBerrorCode\fR will be the
|
|
process's identifier (in decimal).
|
|
The third element will be the symbolic name of the signal that caused
|
|
the process to terminate; it will be one of the names from the
|
|
include file signal.h, such as \fBSIGPIPE\fR.
|
|
The fourth element will be a short human-readable message
|
|
describing the signal, such as ``write on pipe with no readers''
|
|
for \fBSIGPIPE\fR.
|
|
.TP
|
|
\fBCHILDSTATUS\fI pid code\fR
|
|
This format is used when a child process has exited with a non-zero
|
|
exit status. The second element of \fBerrorCode\fR will be the
|
|
process's identifier (in decimal) and the third element will be the exit
|
|
code returned by the process (also in decimal).
|
|
.TP
|
|
\fBCHILDSUSP\fI pid sigName msg\fR
|
|
This format is used when a child process has been suspended because
|
|
of a signal.
|
|
The second element of \fBerrorCode\fR will be the process's identifier,
|
|
in decimal.
|
|
The third element will be the symbolic name of the signal that caused
|
|
the process to suspend; this will be one of the names from the
|
|
include file signal.h, such as \fBSIGTTIN\fR.
|
|
The fourth element will be a short human-readable message
|
|
describing the signal, such as ``background tty read''
|
|
for \fBSIGTTIN\fR.
|
|
.TP
|
|
\fBNONE\fR
|
|
This format is used for errors where no additional information is
|
|
available for an error besides the message returned with the
|
|
error. In these cases \fBerrorCode\fR will consist of a list
|
|
containing a single element whose contents are \fBNONE\fR.
|
|
.TP
|
|
\fBPOSIX \fIerrName msg\fR
|
|
.VS
|
|
If the first element of \fBerrorCode\fR is \fBPOSIX\fR, then
|
|
the error occurred during a POSIX kernel call.
|
|
.VE
|
|
The second element of the list will contain the symbolic name
|
|
of the error that occurred, such as \fBENOENT\fR; this will
|
|
be one of the values defined in the include file errno.h.
|
|
The third element of the list will be a human-readable
|
|
message corresponding to \fIerrName\fR, such as
|
|
``no such file or directory'' for the \fBENOENT\fR case.
|
|
.PP
|
|
To set \fBerrorCode\fR, applications should use library
|
|
procedures such as \fBTcl_SetErrorCode\fR and
|
|
.VS
|
|
\fBTcl_PosixError\fR,
|
|
.VE
|
|
or they may invoke the \fBerror\fR command.
|
|
If one of these methods hasn't been used, then the Tcl
|
|
interpreter will reset the variable to \fBNONE\fR after
|
|
the next error.
|
|
.RE
|
|
.TP
|
|
\fBerrorInfo\fR
|
|
After an error has occurred, this string will contain one or more lines
|
|
identifying the Tcl commands and procedures that were being executed
|
|
when the most recent error occurred.
|
|
Its contents take the form of a stack trace showing the various
|
|
nested Tcl commands that had been invoked at the time of the error.
|
|
.TP
|
|
\fBtcl_library\fR
|
|
.VS
|
|
This variable holds the network name of a directory containing the
|
|
system library of Tcl scripts, such as those used for auto-loading.
|
|
The value of this variable is returned by the \fBinfo library\fR command.
|
|
See the \fBlibrary\fR manual entry for details of the facilities
|
|
rovided by the Tcl script library.
|
|
Normally each application or package will have its own application-specific
|
|
script library in addition to the Tcl script library;
|
|
each application should set a global variable with a name like
|
|
\fB$\fIapp\fB_library\fR (where \fIapp\fR is the application's name)
|
|
to hold the network file name for that application's library directory.
|
|
The initial value of \fBtcl_library\fR is set when an interpreter
|
|
is created by searching several different directories until one is
|
|
found that contains an appropriate Tcl startup script.
|
|
If the \fBTCL_LIBRARY\fR environment variable exists, then
|
|
the directory it names is checked first.
|
|
If \fBTCL_LIBRARY\fR isn't set or doesn't refer to an appropriate
|
|
directory, then Tcl checks several other directories based on a
|
|
compiled-in default location, the location of the binary containing
|
|
the application, and the current working directory.
|
|
.VE
|
|
.TP
|
|
\fBtcl_patchLevel\fR
|
|
When an interpreter is created Tcl initializes this variable to
|
|
hold a string giving the current patch level for Tcl, such as
|
|
\fB7.3p2\fR for Tcl 7.3 with the first two official patches, or
|
|
\fB7.4b4\fR for the fourth beta release of Tcl 7.4.
|
|
The value of this variable is returned by the \fBinfo patchlevel\fR
|
|
command.
|
|
.VS br
|
|
.TP
|
|
\fBtcl_platform\fR
|
|
This is an associative array whose elements contain information about
|
|
the platform on which the application is running, such as the name of
|
|
the operating system, its current release number, and the machine's
|
|
instruction set. The elements listed below will always
|
|
be defined, but they may have empty strings as values if Tcl couldn't
|
|
retrieve any relevant information. In addition, extensions
|
|
and applications may add additional values to the array. The
|
|
predefined elements are:
|
|
.RS
|
|
.TP
|
|
\fBmachine\fR
|
|
The instruction set executed by this machine, such as
|
|
\fBPPC\fR, \fB68k\fR, or \fBsun4m\fR. On UNIX machines, this
|
|
is the value returned by \fBuname -m\fR.
|
|
.TP
|
|
\fBos\fR
|
|
The name of the operating system running on this machine, such
|
|
as \fBWin95\fR, \fBMacOS\fR, or \fBSunOS\fR. On UNIX machines,
|
|
this is the value returned by \fBuname -s\fR.
|
|
.TP
|
|
\fBosVersion\fR
|
|
The version number for the operating system running on this machine.
|
|
On UNIX machines, this is the value returned by \fBuname -r\fR.
|
|
.TP
|
|
\fBplatform\fR
|
|
Either \fBwindows\fR, \fBmacintosh\fR, or \fBunix\fR. This identifies the
|
|
general operating environment of the machine.
|
|
.RE
|
|
.VE
|
|
.TP
|
|
\fBtcl_precision\fR
|
|
If this variable is set, it must contain a decimal number giving the
|
|
number of significant digits to include when converting floating-point
|
|
values to strings.
|
|
If this variable is not set then 6 digits are included.
|
|
17 digits is ``perfect'' for IEEE floating-point in that it allows
|
|
double-precision values to be converted to strings and back to
|
|
binary with no loss of precision.
|
|
.VS br
|
|
.TP
|
|
\fBtcl_rcFileName\fR
|
|
This variable is used during initialization to indicate the name of a
|
|
user-specific startup file. If it is set by application-specific
|
|
initialization, then the Tcl startup code will check for the existence
|
|
of this file and \fBsource\fR it if it exists. For example, for \fBwish\fR
|
|
the variable is set to \fB~/.wishrc\fR.
|
|
.VE
|
|
.TP
|
|
\fBtcl_version\fR
|
|
When an interpreter is created Tcl initializes this variable to
|
|
hold the version number for this version of Tcl in the form \fIx.y\fR.
|
|
Changes to \fIx\fR represent major changes with probable
|
|
incompatibilities and changes to \fIy\fR represent small enhancements and
|
|
bug fixes that retain backward compatibility.
|
|
The value of this variable is returned by the \fBinfo tclversion\fR
|
|
command.
|
|
|
|
.SH KEYWORDS
|
|
arithmetic, error, environment, POSIX, precision, subprocess, variables
|