1tclvars(n)                   Tcl Built-In Commands                  tclvars(n)
2
3
4
5______________________________________________________________________________
6

NAME

8       tclvars - Variables used by Tcl
9_________________________________________________________________
10

DESCRIPTION

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
17       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
28              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
40              The following elements of env are special to Tcl:
41
42              env(HOME)
43                     This  environment variable, if set, gives the location of
44                     the directory considered to be the  current  user's  home
45                     directory, and to which a call of cd without arguments or
46                     with just “~” as an argument will change into. Most plat‐
47                     forms set this correctly by default; it does not normally
48                     need to be set by user code.
49
50              env(TCL_LIBRARY)
51                     If set, then it specifies the location of  the  directory
52                     containing  library  scripts  (the value of this variable
53                     will be assigned to the tcl_library variable  and  there‐
54                     fore  returned  by  the  command  info library).  If this
55                     variable is not set then a default value is used.
56
57                     Note that this environment variable should  not  normally
58                     be set.
59
60              env(TCLLIBPATH)
61                     If  set,  then  it  must  contain a valid Tcl list giving
62                     directories  to  search  during   auto-load   operations.
63                     Directories must be specified in Tcl format, using “/” as
64                     the path separator, regardless of platform.   This  vari‐
65                     able  is  only used when initializing the auto_path vari‐
66                     able.
67
68              env(TCL_INTERP_DEBUG_FRAME)
69                     If existing, it has the same  effect  as  running  interp
70                     debug  {}  -frame 1 as the very first command of each new
71                     Tcl interpreter.
72
73       errorCode
74              This variable holds the value of the  -errorcode  return  option
75              set  by the most recent error that occurred in this interpreter.
76              This list value  represents  additional  information  about  the
77              error  in  a  form  that  is easy to process with programs.  The
78              first element of the list identifies a general class of  errors,
79              and  determines the format of the rest of the list.  The follow‐
80              ing formats for -errorcode return options are used  by  the  Tcl
81              core; individual applications may define additional formats.
82
83              ARITH code msg
84                     This format is used when an arithmetic error occurs (e.g.
85                     an attempt to divide zero by zero in the  expr  command).
86                     Code  identifies  the  precise  error  and msg provides a
87                     human-readable description of the error.   Code  will  be
88                     either DIVZERO (for an attempt to divide by zero), DOMAIN
89                     (if an argument is outside the domain of a function, such
90                     as  acos(-3)), IOVERFLOW (for integer overflow), OVERFLOW
91                     (for a floating-point overflow), or UNKNOWN (if the cause
92                     of the error cannot be determined).
93
94                     Detection of these errors depends in part on the underly‐
95                     ing hardware and system libraries.
96
97              CHILDKILLED pid sigName msg
98                     This format is used when a child process has been  killed
99                     because  of  a  signal.   The  pid  element  will  be the
100                     process's identifier (in decimal).  The  sigName  element
101                     will  be  the symbolic name of the signal that caused the
102                     process to terminate; it will be one of  the  names  from
103                     the include file signal.h, such as SIGPIPE.  The msg ele‐
104                     ment will be a short  human-readable  message  describing
105                     the  signal,  such as “write on pipe with no readers” for
106                     SIGPIPE.
107
108              CHILDSTATUS pid code
109                     This format is used when a child process has exited  with
110                     a  non-zero  exit  status.   The  pid element will be the
111                     process's identifier (in decimal) and  the  code  element
112                     will  be  the  exit code returned by the process (also in
113                     decimal).
114
115              CHILDSUSP pid sigName msg
116                     This format is used when a child process  has  been  sus‐
117                     pended  because of a signal.  The pid element will be the
118                     process's identifier, in decimal.   The  sigName  element
119                     will  be  the symbolic name of the signal that caused the
120                     process to suspend; this will be one of  the  names  from
121                     the include file signal.h, such as SIGTTIN.  The msg ele‐
122                     ment will be a short  human-readable  message  describing
123                     the signal, such as “background tty read” for SIGTTIN.
124
125              NONE   This format is used for errors where no additional infor‐
126                     mation is available for  an  error  besides  the  message
127                     returned  with  the error.  In these cases the -errorcode
128                     return option will consist of a list containing a  single
129                     element whose contents are NONE.
130
131              POSIX errName msg
132                     If  the  first  element is POSIX, then the error occurred
133                     during a POSIX kernel call.   The  errName  element  will
134                     contain  the  symbolic  name  of the error that occurred,
135                     such as ENOENT; this will be one of the values defined in
136                     the  include  file  errno.h.   The  msg element will be a
137                     human-readable message corresponding to errName, such  as
138                     “no such file or directory” for the ENOENT case.
139
140              To  set  the  -errorcode  return option, applications should use
141              library procedures such as Tcl_SetObjErrorCode, Tcl_SetReturnOp‐
142              tions,  and  Tcl_PosixError,  or  they may invoke the -errorcode
143              option of the return command.  If none of these methods for set‐
144              ting  the  error  code  has  been used, the Tcl interpreter will
145              reset the variable to NONE after the next error.
146
147       errorInfo
148              This variable holds the value of the  -errorinfo  return  option
149              set  by the most recent error that occurred in this interpreter.
150              This string value will contain one or more lines identifying the
151              Tcl  commands  and  procedures that were being executed when the
152              most recent error occurred.  Its contents take  the  form  of  a
153              stack  trace  showing  the  various nested Tcl commands that had
154              been invoked at the time of the error.
155
156       tcl_library
157              This variable holds the name of a directory containing the  sys‐
158              tem library of Tcl scripts, such as those used for auto-loading.
159              The value of this variable is returned by the info library  com‐
160              mand.   See  the library manual entry for details of the facili‐
161              ties provided by the Tcl script library.  Normally each applica‐
162              tion  or  package  will have its own application-specific script
163              library in addition to the Tcl script library; each  application
164              should  set  a  global  variable  with  a name like $app_library
165              (where app is the application's name) to hold the  network  file
166              name  for  that  application's  library  directory.  The initial
167              value of tcl_library is set when an interpreter  is  created  by
168              searching  several different directories until one is found that
169              contains an appropriate Tcl startup script.  If the  TCL_LIBRARY
170              environment  variable  exists,  then  the  directory it names is
171              checked first.  If TCL_LIBRARY is not set or doesn't refer to an
172              appropriate directory, then Tcl checks several other directories
173              based on a compiled-in default location,  the  location  of  the
174              binary  containing  the  application,  and  the  current working
175              directory.
176
177       tcl_patchLevel
178              When an interpreter is created Tcl initializes this variable  to
179              hold  a  string  giving the current patch level for Tcl, such as
180              8.4.16 for Tcl 8.4 with the first sixteen official  patches,  or
181              8.5b3  for the third beta release of Tcl 8.5.  The value of this
182              variable is returned by the info patchlevel command.
183
184       tcl_pkgPath
185              This variable holds a list of directories indicating where pack‐
186              ages  are  normally  installed.   It is not used on Windows.  It
187              typically contains either one or two entries; if it contains two
188              entries,  the  first is normally a directory for platform-depen‐
189              dent packages (e.g., shared library binaries) and the second  is
190              normally  a  directory  for platform-independent packages (e.g.,
191              script files). Typically a package is installed as  a  subdirec‐
192              tory  of  one of the entries in $tcl_pkgPath. The directories in
193              $tcl_pkgPath are included by default in the auto_path  variable,
194              so  they  and  their  immediate subdirectories are automatically
195              searched for packages during package  require  commands.   Note:
196              tcl_pkgPath  is  not intended to be modified by the application.
197              Its value is added to auto_path at startup; changes to  tcl_pkg‐
198              Path  are not reflected in auto_path.  If you want Tcl to search
199              additional directories for packages you should add the names  of
200              those directories to auto_path, not tcl_pkgPath.
201
202       tcl_platform
203              This  is an associative array whose elements contain information
204              about the platform on which the application is running, such  as
205              the  name  of  the operating system, its current release number,
206              and the machine's instruction set.  The  elements  listed  below
207              will  always be defined, but they may have empty strings as val‐
208              ues if Tcl could not  retrieve  any  relevant  information.   In
209              addition,  extensions and applications may add additional values
210              to the array.  The predefined elements are:
211
212              byteOrder
213                     The native byte order of this machine:  either  littleEn‐
214                     dian or bigEndian.
215
216              debug  If  this  variable  exists, then the interpreter was com‐
217                     piled with and linked  to  a  debug-enabled  C  run-time.
218                     This  variable  will  only exist on Windows, so extension
219                     writers can specify which package to  load  depending  on
220                     the  C  run-time  library that is in use.  This is not an
221                     indication that this core contains symbols.
222
223              machine
224                     The instruction set executed by  this  machine,  such  as
225                     intel, PPC, 68k, or sun4m.  On UNIX machines, this is the
226                     value returned by uname -m.
227
228              os     The name of the operating system running on this machine,
229                     such  as  Windows  95,  Windows  NT,  or  SunOS.  On UNIX
230                     machines, this is the value returned  by  uname  -s.   On
231                     Windows  95  and  Windows  98, the value returned will be
232                     Windows 95 to provide better backwards  compatibility  to
233                     Windows  95;  to  distinguish  between the two, check the
234                     osVersion.
235
236              osVersion
237                     The version number for the operating  system  running  on
238                     this  machine.   On  UNIX  machines,  this  is  the value
239                     returned by uname -r.  On Windows 95, the version will be
240                     4.0; on Windows 98, the version will be 4.10.
241
242              platform
243                     Either  windows,  or  unix.   This identifies the general
244                     operating environment of the machine.
245
246              threaded
247                     If this variable exists, then the  interpreter  was  com‐
248                     piled with threads enabled.
249
250              user   This  identifies  the  current  user  based  on the login
251                     information available on the platform.  This  comes  from
252                     the USER or LOGNAME environment variable on Unix, and the
253                     value from GetUserName on Windows.
254
255              wordSize
256                     This gives the size of the native-machine word  in  bytes
257                     (strictly,  it  is  same  as  the  result  of  evaluating
258                     sizeof(long) in C.)
259
260              pointerSize
261                     This gives the size  of  the  native-machine  pointer  in
262                     bytes  (strictly,  it is same as the result of evaluating
263                     sizeof(void*) in C.)
264
265       tcl_precision
266              This variable controls the number of  digits  to  generate  when
267              converting  floating-point values to strings.  It defaults to 0.
268              Applications should not change this value; it  is  provided  for
269              compatibility with legacy code.
270
271              The  default value of 0 is special, meaning that Tcl should con‐
272              vert numbers using as few digits as possible while still distin‐
273              guishing  any floating point number from its nearest neighbours.
274              It differs from using an arbitrarily high value  for  tcl_preci‐
275              sion  in  that  an  inexact  number like 1.4 will convert as 1.4
276              rather than 1.3999999999999999 even though the latter is  nearer
277              to the exact value of the binary number.
278
279              If  tcl_precision is not zero, then when Tcl converts a floating
280              point number, it creates a decimal  representation  of  at  most
281              tcl_precision  significant  digits; the result may be shorter if
282              the shorter result represents the original number exactly. If no
283              result  of  at most tcl_precision digits is an exact representa‐
284              tion of the original number, the one  that  is  closest  to  the
285              original  number  is  chosen.   If the original number lies pre‐
286              cisely between two  equally  accurate  decimal  representations,
287              then  the one with an even value for the least significant digit
288              is chosen; for instance, if tcl_precision is 3, then 0.3125 will
289              convert to 0.312, not 0.313, while 0.6875 will convert to 0.688,
290              not 0.687.  Any  string  of  trailing  zeroes  that  remains  is
291              trimmed.
292
293              a  tcl_precision value of 17 digits is “perfect” for IEEE float‐
294              ing-point in that it allows double-precision values to  be  con‐
295              verted  to  strings  and back to binary with no loss of informa‐
296              tion. For this reason, you will often  see  it  as  a  value  in
297              legacy  code  that must run on Tcl versions before 8.5. It is no
298              longer recommended; as noted above, a zero  value  is  the  pre‐
299              ferred method.
300
301              All interpreters in a thread share a single tcl_precision value:
302              changing it in one interpreter  will  affect  all  other  inter‐
303              preters  as  well.   Safe interpreters are not allowed to modify
304              the variable.
305
306              Valid values for tcl_precision range from 0 to 17.
307
308       tcl_rcFileName
309              This variable is used during initialization to indicate the name
310              of  a  user-specific startup file.  If it is set by application-
311              specific initialization, then the Tcl startup  code  will  check
312              for  the existence of this file and source it if it exists.  For
313              example, for wish the variable is set to ~/.wishrc for Unix  and
314              ~/wishrc.tcl for Windows.
315
316       tcl_traceCompile
317              The  value of this variable can be set to control how much trac‐
318              ing information is displayed during  bytecode  compilation.   By
319              default,  tcl_traceCompile  is  zero  and no information is dis‐
320              played.  Setting tcl_traceCompile to 1 generates a one-line sum‐
321              mary in stdout whenever a procedure or top-level command is com‐
322              piled.  Setting it to 2 generates a detailed listing  in  stdout
323              of  the  bytecode instructions emitted during every compilation.
324              This variable is useful in tracking down suspected problems with
325              the Tcl compiler.
326
327              This  variable and functionality only exist if TCL_COMPILE_DEBUG
328              was defined during Tcl's compilation.
329
330       tcl_traceExec
331              The value of this variable can be set to control how much  trac‐
332              ing  information  is  displayed  during  bytecode execution.  By
333              default, tcl_traceExec is zero and no information is  displayed.
334              Setting  tcl_traceExec to 1 generates a one-line trace in stdout
335              on each call to a Tcl procedure.  Setting it to  2  generates  a
336              line of output whenever any Tcl command is invoked that contains
337              the name of the command and its arguments.  Setting it to 3 pro‐
338              duces  a  detailed  trace  showing  the result of executing each
339              bytecode instruction.  Note that when tcl_traceExec is 2  or  3,
340              commands  such  as set and incr that have been entirely replaced
341              by a sequence of bytecode instructions are not  shown.   Setting
342              this variable is useful in tracking down suspected problems with
343              the bytecode compiler and interpreter.
344
345              This variable and functionality only exist if  TCL_COMPILE_DEBUG
346              was defined during Tcl's compilation.
347
348       tcl_wordchars
349              The  value  of this variable is a regular expression that can be
350              set to  control  what  are  considered  “word”  characters,  for
351              instances  like  selecting  a word by double-clicking in text in
352              Tk.  It is platform dependent.  On Windows, it defaults  to  \S,
353              meaning  anything  but  a Unicode space character.  Otherwise it
354              defaults to \w, which is any  Unicode  word  character  (number,
355              letter, or underscore).
356
357       tcl_nonwordchars
358              The  value  of this variable is a regular expression that can be
359              set to control what are considered  “non-word”  characters,  for
360              instances  like  selecting  a word by double-clicking in text in
361              Tk.  It is platform dependent.  On Windows, it defaults  to  \s,
362              meaning  any  Unicode space character.  Otherwise it defaults to
363              \W, which is anything but a Unicode word character (number, let‐
364              ter, or underscore).
365
366       tcl_version
367              When  an interpreter is created Tcl initializes this variable to
368              hold the version number for this version of Tcl in the form x.y.
369              Changes to x represent major changes with probable incompatibil‐
370              ities and changes to y  represent  small  enhancements  and  bug
371              fixes  that  retain  backward  compatibility.  The value of this
372              variable is returned by the info tclversion command.
373

OTHER GLOBAL VARIABLES

375       The following variables are only guaranteed to exist in tclsh and  wish
376       executables;  the  Tcl library does not define them itself but many Tcl
377       environments do.
378
379       argc  The number of arguments to tclsh or wish.
380
381       argv  Tcl list of arguments to tclsh or wish.
382
383       argv0 The script that tclsh or wish started executing (if it was speci‐
384             fied) or otherwise the name by which tclsh or wish was invoked.
385
386       tcl_interactive
387             Contains  1  if tclsh or wish is running interactively (no script
388             was specified and standard input is a  terminal-like  device),  0
389             otherwise.
390
391       The  wish  executable additionally specifies the following global vari‐
392       able:
393
394       geometry
395             If set, contains the user-supplied geometry specification to  use
396             for the main Tk window.
397

SEE ALSO

399       eval(n), tclsh(1), wish(1)
400

KEYWORDS

402       arithmetic,  bytecode,  compiler, error, environment, POSIX, precision,
403       subprocess, variables
404
405
406
407Tcl                                   8.0                           tclvars(n)
Impressum