diff options
Diffstat (limited to 'tcl8.6/doc/tclvars.n')
| -rw-r--r-- | tcl8.6/doc/tclvars.n | 566 |
1 files changed, 566 insertions, 0 deletions
diff --git a/tcl8.6/doc/tclvars.n b/tcl8.6/doc/tclvars.n new file mode 100644 index 0000000..adefe40 --- /dev/null +++ b/tcl8.6/doc/tclvars.n @@ -0,0 +1,566 @@ +'\" +'\" 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. +'\" +.TH tclvars n 8.0 Tcl "Tcl Built-In Commands" +.so man.macros +.BS +'\" Note: do not modify the .SH NAME line immediately below! +.SH NAME +argc, argv, argv0, auto_path, env, errorCode, errorInfo, tcl_interactive, tcl_library, tcl_nonwordchars, tcl_patchLevel, tcl_pkgPath, tcl_platform, tcl_precision, tcl_rcFileName, tcl_traceCompile, tcl_traceExec, tcl_wordchars, tcl_version \- 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 +\fBauto_path\fR +. +If set, then it must contain a valid Tcl list giving directories to +search during auto-load operations (including for package index +files when using the default \fBpackage unknown\fR handler). +This variable is initialized during startup to contain, in order: +the directories listed in the \fBTCLLIBPATH\fR environment variable, +the directory named by the \fBtcl_library\fR global variable, +the parent directory of \fBtcl_library\fR, +the directories listed in the \fBtcl_pkgPath\fR variable. +Additional locations to look for files and package indices should +normally be added to this variable using \fBlappend\fR. +.RS +.PP +Additional variables relating to package management exist. More +details are listed in the \fBVARIABLES\fR section of the \fBlibrary\fR +manual page. +.RE +.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 does not 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 +.PP +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 +.QW path , +.QW Path , +.QW PaTh , +etc., causing otherwise simple Tcl code to have to +support many special cases. All other environment variables inherited by +Tcl are left unmodified. Setting an env array variable to blank is the +same as unsetting it as this is the behavior of the underlying Windows OS. +It should be noted that relying on an existing and empty environment variable +will not work on Windows and is discouraged for cross-platform usage. +.PP +The following elements of \fBenv\fR are special to Tcl: +.TP +\fBenv(HOME)\fR +. +This environment variable, if set, gives the location of the directory +considered to be the current user's home directory, and to which a +call of \fBcd\fR without arguments or with just +.QW ~ +as an argument will change into. Most platforms set this correctly by +default; it does not normally need to be set by user code. +.TP +\fBenv(TCL_LIBRARY)\fR +. +If set, then it specifies the location of the directory containing +library scripts (the value of this variable will be +assigned to the \fBtcl_library\fR variable and therefore returned by +the command \fBinfo library\fR). If this variable is not set then +a default value is used. +.RS +.PP +Note that this environment variable should \fInot\fR normally be set. +.RE +.TP +\fBenv(TCLLIBPATH)\fR +. +If set, then it must contain a valid Tcl list giving directories to +search during auto-load operations. Directories must be specified in +Tcl format, using +.QW / +as the path separator, regardless of platform. +This variable is only used when initializing the \fBauto_path\fR variable. +.TP +\fBenv(TCL_TZ)\fR, \fBenv(TZ)\fR +. +These specify the default timezone used for parsing and formatting times and +dates in the \fBclock\fR command. On many platforms, the TZ environment +variable is set up by the operating system. +.TP +\fBenv(LC_ALL)\fR, \fBenv(LC_MESSAGES)\fR, \fBenv(LANG)\fR +. +These environment variables are used by the \fBmsgcat\fR package to +determine what locale to format messages using. +.TP +\fBenv(TCL_INTERP_DEBUG_FRAME)\fR +. +If existing, it has the same effect as running \fBinterp debug\fR +\fB{} -frame 1\fR +as the very first command of each new Tcl interpreter. +.RE +.TP +\fBerrorCode\fR +. +This variable holds the value of the \fB\-errorcode\fR return option +set by the most recent error that occurred in this interpreter. +This list value represents additional information about the error +in a form that is easy to process with programs. +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 \fB\-errorcode\fR return options +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 zero 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). +.RS +.PP +Detection of these errors depends in part on the underlying hardware +and system libraries. +.RE +.TP +\fBCHILDKILLED\fI pid sigName msg\fR +. +This format is used when a child process has been killed because of +a signal. The \fIpid\fR element will be the process's identifier (in decimal). +The \fIsigName\fR 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 \fImsg\fR element will be a short human-readable message +describing the signal, such as +.QW "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 \fIpid\fR element will be the +process's identifier (in decimal) and the \fIcode\fR 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 \fIpid\fR element will be the process's identifier, in decimal. +The \fIsigName\fR 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 \fImsg\fR element will be a short human-readable message +describing the signal, such as +.QW "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 the \fB\-errorcode\fR return option +will consist of a list containing a single element whose +contents are \fBNONE\fR. +.TP +\fBPOSIX \fIerrName msg\fR +. +If the first element is \fBPOSIX\fR, then +the error occurred during a POSIX kernel call. +The \fIerrName\fR element 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 \fImsg\fR element will be a human-readable +message corresponding to \fIerrName\fR, such as +.QW "no such file or directory" +for the \fBENOENT\fR case. +.TP +\fBTCL\fR ... +. +Indicates some sort of problem generated in relation to Tcl itself, e.g. a +failure to look up a channel or variable. +.PP +To set the \fB\-errorcode\fR return option, applications should use library +procedures such as \fBTcl_SetObjErrorCode\fR, \fBTcl_SetReturnOptions\fR, +and \fBTcl_PosixError\fR, or they may invoke the \fB\-errorcode\fR +option of the \fBreturn\fR command. +If none of these methods for setting the error code has been used, +the Tcl interpreter will reset the variable to \fBNONE\fR after +the next error. +.RE +.TP +\fBerrorInfo\fR +. +This variable holds the value of the \fB\-errorinfo\fR return option +set by the most recent error that occurred in this interpreter. +This string value 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 is not 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 +\fB8.4.16\fR for Tcl 8.4 with the first sixteen official patches, or +\fB8.5b3\fR for the third beta release of Tcl 8.5. +The value of this variable is returned by the \fBinfo patchlevel\fR +command. +.TP +\fBtcl_pkgPath\fR +. +This variable holds a list of directories indicating where packages are +normally installed. It is not used on Windows. 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 the \fBtcl_pkgPath\fR +variable. The directories in the \fBtcl_pkgPath\fR variable 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 is 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. +.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 could not +retrieve any relevant information. In addition, extensions +and applications may add additional values to the array. The +predefined elements are: +.RS +.TP +\fBbyteOrder\fR +. +The native byte order of this machine: either \fBlittleEndian\fR or +\fBbigEndian\fR. +.TP +\fBdebug\fR +. +If this variable exists, then the interpreter was compiled with and linked +to a debug-enabled C run-time. This variable will only exist on Windows, +so extension writers can specify which package to load depending on the +C run-time library that is in use. This is not an indication that this core +contains symbols. +.TP +\fBengine\fR +. +The name of the Tcl language implementation. When the interpreter is first +created, this is always set to the string \fBTcl\fR. +.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 \fBWindows NT\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 +\fBpathSeparator\fR +.VS 8.6 +'\" Defined by TIP #315 +The character that should be used to \fBsplit\fR PATH-like environment +variables into their corresponding list of directory names. +.VE 8.6 +.TP +\fBplatform\fR +. +Either \fBwindows\fR, or \fBunix\fR. This identifies the +general operating environment of the machine. +.TP +\fBpointerSize\fR +. +This gives the size of the native-machine pointer in bytes (strictly, it +is same as the result of evaluating \fIsizeof(void*)\fR in C.) +.TP +\fBthreaded\fR +. +If this variable exists, then the interpreter +was compiled with threads enabled. +.TP +\fBuser\fR +. +This identifies the +current user based on the login information available on the platform. +This value comes from the getuid() and getpwuid() system calls on Unix, +and the value from the GetUserName() system call on Windows. +.TP +\fBwordSize\fR +. +This gives the size of the native-machine word in bytes (strictly, it +is same as the result of evaluating \fIsizeof(long)\fR in C.) +.RE +.TP +\fBtcl_precision\fR +. +This variable controls the number of digits to generate +when converting floating-point values to strings. It defaults +to 0. \fIApplications should not change this value;\fR it is +provided for compatibility with legacy code. +.PP +.RS +The default value of 0 is special, meaning that Tcl should +convert numbers using as few digits as possible while still +distinguishing any floating point number from its nearest +neighbours. It differs from using an arbitrarily high value +for \fItcl_precision\fR in that an inexact number like \fI1.4\fR +will convert as \fI1.4\fR rather than \fI1.3999999999999999\fR +even though the latter is nearer to the exact value of the +binary number. +.RE +.PP +.RS +If \fBtcl_precision\fR is not zero, then when Tcl converts a floating +point number, it creates a decimal representation of at most +\fBtcl_precision\fR significant digits; the result may be shorter if +the shorter result represents the original number exactly. If no +result of at most \fBtcl_precision\fR digits is an exact representation +of the original number, the one that is closest to the original +number is chosen. +If the original number lies precisely between two equally accurate +decimal representations, then the one with an even value for the least +significant digit is chosen; for instance, if \fBtcl_precision\fR is 3, then +0.3125 will convert to 0.312, not 0.313, while 0.6875 will convert to +0.688, not 0.687. Any string of trailing zeroes that remains is trimmed. +.RE +.PP +.RS +a \fBtcl_precision\fR value of 17 digits is +.QW 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. For this reason, you will often +see it as a value in legacy code that must run on Tcl versions before +8.5. It is no longer recommended; as noted above, a zero value is the +preferred method. +.RE +.PP +.RS +All interpreters in a thread share a single \fBtcl_precision\fR value: +changing it in one interpreter will affect all other interpreters as +well. Safe interpreters are not allowed to modify the +variable. +.RE +.PP +.RS +Valid values for \fBtcl_precision\fR range from 0 to 17. +.RE +.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_traceCompile\fR +. +The value of this variable can be set to control +how much tracing information +is displayed during bytecode compilation. +By default, \fBtcl_traceCompile\fR is zero and no information is displayed. +Setting \fBtcl_traceCompile\fR to 1 generates a one-line summary in \fBstdout\fR +whenever a procedure or top-level command is compiled. +Setting it to 2 generates a detailed listing in \fBstdout\fR of the +bytecode instructions emitted during every compilation. +This variable is useful in +tracking down suspected problems with the Tcl compiler. +.PP +.RS +This variable and functionality only exist if +\fBTCL_COMPILE_DEBUG\fR was defined during Tcl's compilation. +.RE +.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, \fBtcl_traceExec\fR is zero and no information is displayed. +Setting \fBtcl_traceExec\fR to 1 generates a one-line trace in \fBstdout\fR +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 \fBtcl_traceExec\fR is 2 or 3, +commands such as \fBset\fR and \fBincr\fR +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. +.PP +.RS +This variable and functionality only exist if +\fBTCL_COMPILE_DEBUG\fR was defined during Tcl's compilation. +.RE +.TP +\fBtcl_wordchars\fR +. +The value of this variable is a regular expression that can be set to +control what are considered +.QW word +characters, for instances like +selecting a word by double-clicking in text in Tk. It is platform +dependent. On Windows, it defaults to \fB\eS\fR, meaning anything +but a Unicode space character. Otherwise it defaults to \fB\ew\fR, +which is any Unicode word character (number, letter, or underscore). +.TP +\fBtcl_nonwordchars\fR +. +The value of this variable is a regular expression that can be set to +control what are considered +.QW non-word +characters, for instances like +selecting a word by double-clicking in text in Tk. It is platform +dependent. On Windows, it defaults to \fB\es\fR, meaning any Unicode space +character. Otherwise it defaults to \fB\eW\fR, which is anything but a +Unicode word character (number, letter, or underscore). +.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 "OTHER GLOBAL VARIABLES" +.PP +The following variables are only guaranteed to exist in \fBtclsh\fR +and \fBwish\fR executables; the Tcl library does not define them +itself but many Tcl environments do. +.TP 6 +\fBargc\fR +. +The number of arguments to \fBtclsh\fR or \fBwish\fR. +.TP 6 +\fBargv\fR +. +Tcl list of arguments to \fBtclsh\fR or \fBwish\fR. +.TP 6 +\fBargv0\fR +. +The script that \fBtclsh\fR or \fBwish\fR started executing (if it was +specified) or otherwise the name by which \fBtclsh\fR or \fBwish\fR +was invoked. +.TP 6 +\fBtcl_interactive\fR +. +Contains 1 if \fBtclsh\fR or \fBwish\fR is running interactively (no +script was specified and standard input is a terminal-like device), 0 +otherwise. +.SH EXAMPLES +.PP +To add a directory to the collection of locations searched by +\fBpackage require\fR, e.g., because of some application-specific +packages that are used, the \fBauto_path\fR variable needs to be +updated: +.PP +.CS +lappend ::\fBauto_path\fR [file join [pwd] "theLibDir"] +.CE +.PP +A simple though not very robust way to handle command line arguments +of the form +.QW "\-foo 1 \-bar 2" +is to load them into an array having first loaded in the default settings: +.CS +array set arguments {-foo 0 -bar 0 -grill 0} +array set arguments $::\fBargv\fR +puts "foo is $arguments(-foo)" +puts "bar is $arguments(-bar)" +puts "grill is $arguments(-grill)" +.CE +.PP +The \fBargv0\fR global variable can be used (in conjunction with the +\fBinfo script\fR command) to determine whether the current script is +being executed as the main script or loaded as a library. This is +useful because it allows a single script to be used as both a library +and a demonstration of that library: +.PP +.CS +if {$::\fBargv0\fR eq [info script]} { + # running as: tclsh example.tcl +} else { + package provide Example 1.0 +} +.CE +.SH "SEE ALSO" +eval(n), library(n), tclsh(1), tkvars(n), wish(1) +.SH KEYWORDS +arithmetic, bytecode, compiler, error, environment, POSIX, precision, +subprocess, user, variables +'\" Local Variables: +'\" mode: nroff +'\" End: |