1tclvars(n) Tcl Built-In Commands tclvars(n)
2______________________________________________________________________________
6
8 tclvars - Variables used by Tcl
9_________________________________________________________________
10
12 The following global variables are created and managed automatically by
13 the Tcl library. Except where noted below, these variables should nor‐
14 mally be treated as read-only by application-specific code and by
15 users.
16 env This variable is maintained by Tcl as an array whose elements
18 are the environment variables for the process. Reading an ele‐
19 ment will return the value of the corresponding environment
20 variable. Setting an element of the array will modify the cor‐
21 responding environment variable or create a new one if it does
22 not already exist. Unsetting an element of env will remove the
23 corresponding environment variable. Changes to the env array
24 will affect the environment passed to children by commands like
25 exec. If the entire env array is unset then Tcl will stop moni‐
26 toring env accesses and will not update environment variables.
27 Under Windows, the environment variables PATH and COMSPEC in any
29 capitalization are converted automatically to upper case. For
30 instance, the PATH variable could be exported by the operating
31 system as “path”, “Path”, “PaTh”, etc., causing otherwise simple
32 Tcl code to have to support many special cases. All other envi‐
33 ronment variables inherited by Tcl are left unmodified. Setting
34 an env array variable to blank is the same as unsetting it as
35 this is the behavior of the underlying Windows OS. It should be
36 noted that relying on an existing and empty environment variable
37 will not work on Windows and is discouraged for cross-platform
38 usage.
39 errorCode
41 This variable holds the value of the -errorcode return option
42 set by the most recent error that occurred in this interpreter.
43 This list value represents additional information about the
44 error in a form that is easy to process with programs. The
45 first element of the list identifies a general class of errors,
46 and determines the format of the rest of the list. The follow‐
47 ing formats for -errorcode return options are used by the Tcl
48 core; individual applications may define additional formats.
49 ARITH code msg
51 This format is used when an arithmetic error occurs (e.g.
52 an attempt to divide zero by zero in the expr command).
53 Code identifies the precise error and msg provides a
54 human-readable description of the error. Code will be
55 either DIVZERO (for an attempt to divide by zero), DOMAIN
56 (if an argument is outside the domain of a function, such
57 as acos(-3)), IOVERFLOW (for integer overflow), OVERFLOW
58 (for a floating-point overflow), or UNKNOWN (if the cause
59 of the error cannot be determined).
60 Detection of these errors depends in part on the underly‐
62 ing hardware and system libraries.
63 CHILDKILLED pid sigName msg
65 This format is used when a child process has been killed
66 because of a signal. The pid element will be the
67 process's identifier (in decimal). The sigName element
68 will be the symbolic name of the signal that caused the
69 process to terminate; it will be one of the names from
70 the include file signal.h, such as SIGPIPE. The msg ele‐
71 ment will be a short human-readable message describing
72 the signal, such as “write on pipe with no readers” for
73 SIGPIPE.
74 CHILDSTATUS pid code
76 This format is used when a child process has exited with
77 a non-zero exit status. The pid element will be the
78 process's identifier (in decimal) and the code element
79 will be the exit code returned by the process (also in
80 decimal).
81 CHILDSUSP pid sigName msg
83 This format is used when a child process has been sus‐
84 pended because of a signal. The pid element will be the
85 process's identifier, in decimal. The sigName element
86 will be the symbolic name of the signal that caused the
87 process to suspend; this will be one of the names from
88 the include file signal.h, such as SIGTTIN. The msg ele‐
89 ment will be a short human-readable message describing
90 the signal, such as “background tty read” for SIGTTIN.
91 NONE This format is used for errors where no additional infor‐
93 mation is available for an error besides the message
94 returned with the error. In these cases the -errorcode
95 return option will consist of a list containing a single
96 element whose contents are NONE.
97 POSIX errName msg
99 If the first element is POSIX, then the error occurred
100 during a POSIX kernel call. The errName element will
101 contain the symbolic name of the error that occurred,
102 such as ENOENT; this will be one of the values defined in
103 the include file errno.h. The msg element will be a
104 human-readable message corresponding to errName, such as
105 “no such file or directory” for the ENOENT case.
106 To set the -errorcode return option, applications should use
108 library procedures such as Tcl_SetObjErrorCode, Tcl_SetReturnOp‐
109 tions, and Tcl_PosixError, or they may invoke the -errorcode
110 option of the return command. If none of these methods for set‐
111 ting the error code has been used, the Tcl interpreter will
112 reset the variable to NONE after the next error.
113 errorInfo
115 This variable holds the value of the -errorinfo return option
116 set by the most recent error that occurred in this interpreter.
117 This string value will contain one or more lines identifying the
118 Tcl commands and procedures that were being executed when the
119 most recent error occurred. Its contents take the form of a
120 stack trace showing the various nested Tcl commands that had
121 been invoked at the time of the error.
122 tcl_library
124 This variable holds the name of a directory containing the sys‐
125 tem library of Tcl scripts, such as those used for auto-loading.
126 The value of this variable is returned by the info library com‐
127 mand. See the library manual entry for details of the facili‐
128 ties provided by the Tcl script library. Normally each applica‐
129 tion or package will have its own application-specific script
130 library in addition to the Tcl script library; each application
131 should set a global variable with a name like $app_library
132 (where app is the application's name) to hold the network file
133 name for that application's library directory. The initial
134 value of tcl_library is set when an interpreter is created by
135 searching several different directories until one is found that
136 contains an appropriate Tcl startup script. If the TCL_LIBRARY
137 environment variable exists, then the directory it names is
138 checked first. If TCL_LIBRARY is not set or doesn't refer to an
139 appropriate directory, then Tcl checks several other directories
140 based on a compiled-in default location, the location of the
141 binary containing the application, and the current working
142 directory.
143 tcl_patchLevel
145 When an interpreter is created Tcl initializes this variable to
146 hold a string giving the current patch level for Tcl, such as
147 8.4.16 for Tcl 8.4 with the first sixteen official patches, or
148 8.5b3 for the third beta release of Tcl 8.5. The value of this
149 variable is returned by the info patchlevel command.
150 tcl_pkgPath
152 This variable holds a list of directories indicating where pack‐
153 ages are normally installed. It is not used on Windows. It
154 typically contains either one or two entries; if it contains two
155 entries, the first is normally a directory for platform-depen‐
156 dent packages (e.g., shared library binaries) and the second is
157 normally a directory for platform-independent packages (e.g.,
158 script files). Typically a package is installed as a subdirec‐
159 tory of one of the entries in $tcl_pkgPath. The directories in
160 $tcl_pkgPath are included by default in the auto_path variable,
161 so they and their immediate subdirectories are automatically
162 searched for packages during package require commands. Note:
163 tcl_pkgPath is not intended to be modified by the application.
164 Its value is added to auto_path at startup; changes to tcl_pkg‐
165 Path are not reflected in auto_path. If you want Tcl to search
166 additional directories for packages you should add the names of
167 those directories to auto_path, not tcl_pkgPath.
168 tcl_platform
170 This is an associative array whose elements contain information
171 about the platform on which the application is running, such as
172 the name of the operating system, its current release number,
173 and the machine's instruction set. The elements listed below
174 will always be defined, but they may have empty strings as val‐
175 ues if Tcl could not retrieve any relevant information. In
176 addition, extensions and applications may add additional values
177 to the array. The predefined elements are:
178 byteOrder
180 The native byte order of this machine: either littleEn‐
181 dian or bigEndian.
182 debug If this variable exists, then the interpreter was com‐
184 piled with and linked to a debug-enabled C run-time.
185 This variable will only exist on Windows, so extension
186 writers can specify which package to load depending on
187 the C run-time library that is in use. This is not an
188 indication that this core contains symbols.
189 machine
191 The instruction set executed by this machine, such as
192 intel, PPC, 68k, or sun4m. On UNIX machines, this is the
193 value returned by uname -m.
194 os The name of the operating system running on this machine,
196 such as Windows 95, Windows NT, or SunOS. On UNIX
197 machines, this is the value returned by uname -s. On
198 Windows 95 and Windows 98, the value returned will be
199 Windows 95 to provide better backwards compatibility to
200 Windows 95; to distinguish between the two, check the
201 osVersion.
202 osVersion
204 The version number for the operating system running on
205 this machine. On UNIX machines, this is the value
206 returned by uname -r. On Windows 95, the version will be
207 4.0; on Windows 98, the version will be 4.10.
208 platform
210 Either windows, or unix. This identifies the general
211 operating environment of the machine.
212 threaded
214 If this variable exists, then the interpreter was com‐
215 piled with threads enabled.
216 user This identifies the current user based on the login
218 information available on the platform. This comes from
219 the USER or LOGNAME environment variable on Unix, and the
220 value from GetUserName on Windows.
221 wordSize
223 This gives the size of the native-machine word in bytes
224 (strictly, it is same as the result of evaluating
225 sizeof(long) in C.)
226 pointerSize
228 This gives the size of the native-machine pointer in
229 bytes (strictly, it is same as the result of evaluating
230 sizeof(void*) in C.)
231 tcl_precision
233 This variable controls the number of digits to generate when
234 converting floating-point values to strings. It defaults to 0. │
235 Applications should not change this value; it is provided for │
236 compatibility with legacy code. │
237 The default value of 0 is special, meaning that Tcl should con‐ │
239 vert numbers using as few digits as possible while still distin‐ │
240 guishing any floating point number from its nearest neighbours. │
241 It differs from using an arbitrarily high value for tcl_preci‐ │
242 sion in that an inexact number like 1.4 will convert as 1.4 │
243 rather than 1.3999999999999999 even though the latter is nearer │
244 to the exact value of the binary number. │
245 17 digits is “perfect” for IEEE floating-point in that it allows
247 double-precision values to be converted to strings and back to
248 binary with no loss of information. However, using 17 digits
249 prevents any rounding, which produces longer, less intuitive
250 results. For example, expr {1.4} returns 1.3999999999999999
251 with tcl_precision set to 17, vs. 1.4 if tcl_precision is 12.
252 All interpreters in a thread share a single tcl_precision value:
254 changing it in one interpreter will affect all other inter‐
255 preters as well. However, safe interpreters are not allowed to
256 modify the variable.
257 tcl_rcFileName
259 This variable is used during initialization to indicate the name
260 of a user-specific startup file. If it is set by application-
261 specific initialization, then the Tcl startup code will check
262 for the existence of this file and source it if it exists. For
263 example, for wish the variable is set to ~/.wishrc for Unix and
264 ~/wishrc.tcl for Windows.
265 tcl_traceCompile
267 The value of this variable can be set to control how much trac‐
268 ing information is displayed during bytecode compilation. By
269 default, tcl_traceCompile is zero and no information is dis‐
270 played. Setting tcl_traceCompile to 1 generates a one-line sum‐
271 mary in stdout whenever a procedure or top-level command is com‐
272 piled. Setting it to 2 generates a detailed listing in stdout
273 of the bytecode instructions emitted during every compilation.
274 This variable is useful in tracking down suspected problems with
275 the Tcl compiler.
276 This variable and functionality only exist if TCL_COMPILE_DEBUG
278 was defined during Tcl's compilation.
279 tcl_traceExec
281 The value of this variable can be set to control how much trac‐
282 ing information is displayed during bytecode execution. By
283 default, tcl_traceExec is zero and no information is displayed.
284 Setting tcl_traceExec to 1 generates a one-line trace in stdout
285 on each call to a Tcl procedure. Setting it to 2 generates a
286 line of output whenever any Tcl command is invoked that contains
287 the name of the command and its arguments. Setting it to 3 pro‐
288 duces a detailed trace showing the result of executing each
289 bytecode instruction. Note that when tcl_traceExec is 2 or 3,
290 commands such as set and incr that have been entirely replaced
291 by a sequence of bytecode instructions are not shown. Setting
292 this variable is useful in tracking down suspected problems with
293 the bytecode compiler and interpreter.
294 This variable and functionality only exist if TCL_COMPILE_DEBUG
296 was defined during Tcl's compilation.
297 tcl_wordchars
299 The value of this variable is a regular expression that can be
300 set to control what are considered “word” characters, for
301 instances like selecting a word by double-clicking in text in
302 Tk. It is platform dependent. On Windows, it defaults to \S,
303 meaning anything but a Unicode space character. Otherwise it
304 defaults to \w, which is any Unicode word character (number,
305 letter, or underscore).
306 tcl_nonwordchars
308 The value of this variable is a regular expression that can be
309 set to control what are considered “non-word” characters, for
310 instances like selecting a word by double-clicking in text in
311 Tk. It is platform dependent. On Windows, it defaults to \s,
312 meaning any Unicode space character. Otherwise it defaults to
313 \W, which is anything but a Unicode word character (number, let‐
314 ter, or underscore).
315 tcl_version
317 When an interpreter is created Tcl initializes this variable to
318 hold the version number for this version of Tcl in the form x.y.
319 Changes to x represent major changes with probable incompatibil‐
320 ities and changes to y represent small enhancements and bug
321 fixes that retain backward compatibility. The value of this
322 variable is returned by the info tclversion command.
323
325 The following variables are only guaranteed to exist in tclsh and wish
326 executables; the Tcl library does not define them itself but many Tcl
327 environments do.
328 argc The number of arguments to tclsh or wish.
330 argv Tcl list of arguments to tclsh or wish.
332 argv0 The script that tclsh or wish started executing (if it was speci‐
334 fied) or otherwise the name by which tclsh or wish was invoked.
335 tcl_interactive
337 Contains 1 if tclsh or wish is running interactively (no script
338 was specified and standard input is a terminal-like device), 0
339 otherwise.
340 The wish executable additionally specifies the following global vari‐
342 able:
343 geometry
345 If set, contains the user-supplied geometry specification to use
346 for the main Tk window.
347
349 eval(n), tclsh(1), wish(1)
350
352 arithmetic, bytecode, compiler, error, environment, POSIX, precision,
353 subprocess, variables
354Tcl 8.0 tclvars(n)