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