diff options
Diffstat (limited to 'contrib/tcl/doc/tclvars.n')
-rw-r--r-- | contrib/tcl/doc/tclvars.n | 220 |
1 files changed, 220 insertions, 0 deletions
diff --git a/contrib/tcl/doc/tclvars.n b/contrib/tcl/doc/tclvars.n new file mode 100644 index 0000000..47f1b15 --- /dev/null +++ b/contrib/tcl/doc/tclvars.n @@ -0,0 +1,220 @@ +'\" +'\" 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 |