diff options
Diffstat (limited to 'doc/tclvars.n')
| -rw-r--r-- | doc/tclvars.n | 356 |
1 files changed, 356 insertions, 0 deletions
diff --git a/doc/tclvars.n b/doc/tclvars.n new file mode 100644 index 0000000..b689a4f --- /dev/null +++ b/doc/tclvars.n @@ -0,0 +1,356 @@ +'\" +'\" Copyright (c) 1993 The Regents of the University of California. +'\" Copyright (c) 1994-1997 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.34 97/08/22 18:51:04 +'\" +.so man.macros +.TH tclvars n 8.0 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. +.RS +.VS 8.0 +Under Windows, the environment variables PATH and COMSPEC in any +capitalization are converted automatically to upper case. For instance, the +PATH variable could be exported by the operating system as ``path'', +``Path'', ``PaTh'', etc., causing otherwise simple Tcl code to have to +support many special cases. All other environment variables inherited by +Tcl are left unmodified. +.VE +.RE +.RS +On the Macintosh, the environment variable is constructed by Tcl as no +global environment variable exists. The environment variables that +are created for Tcl include: +.TP +\fBLOGIN\fR +This holds the Chooser name of the Macintosh. +.TP +\fBUSER\fR +This also holds the Chooser name of the Macintosh. +.TP +\fBSYS_FOLDER\fR +The path to the system directory. +.TP +\fBAPPLE_M_FOLDER\fR +The path to the Apple Menu directory. +.TP +\fBCP_FOLDER\fR +The path to the control panels directory. +.TP +\fBDESK_FOLDER\fR +The path to the desk top directory. +.TP +\fBEXT_FOLDER\fR +The path to the system extensions directory. +.TP +\fBPREF_FOLDER\fR +The path to the preferences directory. +.TP +\fBPRINT_MON_FOLDER\fR +The path to the print monitor directory. +.TP +\fBSHARED_TRASH_FOLDER\fR +The path to the network trash directory. +.TP +\fBTRASH_FOLDER\fR +The path to the trash directory. +.TP +\fBSTART_UP_FOLDER\fR +The path to the start up directory. +.TP +\fBPWD\fR +The path to the application's default directory. +.PP +You can also create your own environment variables for the Macintosh. +A file named \fITcl Environment Variables\fR may be placed in the +preferences folder in the Mac system folder. Each line of this file +should be of the form \fIVAR_NAME=var_data\fR. +.PP +The last alternative is to place environment variables in a 'STR#' +resource named \fITcl Environment Variables\fR of the application. This +is considered a little more ``Mac like'' than a Unix style Environment +Variable file. Each entry in the 'STR#' resource has the same format +as above. The source code file \fItclMacEnv.c\fR contains the +implementation of the env mechanisms. This file contains many +#define's that allow customization of the env mechanisms to fit your +applications needs. +.RE +.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 +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). +.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 +If the first element of \fBerrorCode\fR is \fBPOSIX\fR, then +the error occurred during a POSIX kernel call. +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 \fBTcl_PosixError\fR, +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 +This variable holds the 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 +provided 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. +.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 8.0 br +.TP +\fBtcl_pkgPath\fR +This variable holds a list of directories indicating where packages are +normally installed. It typically contains either one or two entries; +if it contains two entries, the first is normally a directory for +platform-dependent packages (e.g., shared library binaries) and the +second is normally a directory for platform-independent packages (e.g., +script files). Typically a package is installed as a subdirectory of one +of the entries in \fB$tcl_pkgPath\fR. The directories in +\fB$tcl_pkgPath\fR are included by default in the \fBauto_path\fR +variable, so they and their immediate subdirectories are automatically +searched for packages during \fBpackage require\fR commands. Note: +\fBtcl_pkgPath\fR it not intended to be modified by the application. +Its value is added to \fBauto_path\fR at startup; changes to +\fBtcl_pkgPath\fR are not reflected in \fBauto_path\fR. If you +want Tcl to search additional directories for packages you should add +the names of those directories to \fBauto_path\fR, not \fBtcl_pkgPath\fR. +.VE +.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 +.VS +.TP +\fBbyteOrder\fR +The native byte order of this machine: either \fBlittleEndian\fR or +\fBbigEndian\fR. +.VE +.TP +\fBmachine\fR +The instruction set executed by this machine, such as +\fBintel\fR, \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 \fBWin32s\fR, \fBWindows NT\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 +.TP +\fBtcl_precision\fR +.VS +This variable controls the number of digits to generate +when converting floating-point values to strings. It defaults +to 12. +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 information. However, using 17 digits prevents +any rounding, which produces longer, less intuitive results. For example, +\fBexpr 1.4\fR returns 1.3999999999999999 with \fBtcl_precision\fR +set to 17, vs. 1.4 if \fBtcl_precision\fR is 12. +.RS +All interpreters in a process share a single \fBtcl_precision\fR value: +changing it in one interpreter will affect all other interpreters as +well. However, safe interpreters are not allowed to modify the +variable. +.RE +.VE +.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 for Unix and \fB~/wishrc.tcl\fR +for Windows. +.TP +\fBtcl_rcRsrcName\fR +This variable is only used on Macintosh systems. The variable is used +during initialization to indicate the name of a user-specific +\fBTEXT\fR resource located in the application or extension resource +forks. If it is set by application-specific initialization, then the +Tcl startup code will check for the existence of this resource and +\fBsource\fR it if it exists. For example, the Macintosh \fBwish\fR +application has the variable is set to \fBtclshrc\fR. +.TP +\fBtcl_traceCompile\fR +The value of this variable can be set to control +how much tracing information +is displayed during bytecode compilation. +By default, tcl_traceCompile is zero and no information is displayed. +Setting tcl_traceCompile to 1 generates a one line summary in stdout +whenever a procedure or top level command is compiled. +Setting it to 2 generates a detailed listing in stdout of the +bytecode instructions emitted during every compilation. +This variable is useful in +tracking down suspected problems with the Tcl compiler. +It is also occasionally useful when converting +existing code to use Tcl8.0. +.TP +\fBtcl_traceExec\fR +The value of this variable can be set to control +how much tracing information +is displayed during bytecode execution. +By default, tcl_traceExec is zero and no information is displayed. +Setting tcl_traceExec to 1 generates a one line trace in stdout +on each call to a Tcl procedure. +Setting it to 2 generates a line of output +whenever any Tcl command is invoked +that contains the name of the command and its arguments. +Setting it to 3 produces a detailed trace showing the result of +executing each bytecode instruction. +Note that when tcl_traceExec is 2 or 3, +commands such as set and incr +that have been entirely replaced by a sequence +of bytecode instructions are not shown. +Setting this variable is useful in +tracking down suspected problems with the bytecode compiler +and interpreter. +It is also occasionally useful when converting +code to use Tcl8.0. +.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, bytecode, compiler, error, environment, POSIX, precision, subprocess, variables |