1tclvars(n)                   Tcl Built-In Commands                  tclvars(n)


8       argc,  argv,  argv0, auto_path, env, errorCode, errorInfo, tcl_interac‐
9       tive,  tcl_library,  tcl_nonwordchars,   tcl_patchLevel,   tcl_pkgPath,
10       tcl_platform,    tcl_precision,    tcl_rcFileName,    tcl_traceCompile,
11       tcl_traceExec, tcl_wordchars, tcl_version - Variables used by Tcl


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


415       The  following variables are only guaranteed to exist in tclsh and wish
416       executables; the Tcl library does not define them itself but  many  Tcl
417       environments do.
419       argc  The number of arguments to tclsh or wish.
421       argv  Tcl list of arguments to tclsh or wish.
423       argv0 The script that tclsh or wish started executing (if it was speci‐
424             fied) or otherwise the name by which tclsh or wish was invoked.
426       tcl_interactive
427             Contains 1 if tclsh or wish is running interactively  (no  script
428             was  specified  and  standard input is a terminal-like device), 0
429             otherwise.


432       To add a directory to the collection of locations searched  by  package
433       require,  e.g.,  because of some application-specific packages that are
434       used, the auto_path variable needs to be updated:
436              lappend ::auto_path [file join [pwd] "theLibDir"]
438       A simple though not very robust way to handle command line arguments of
439       the  form  “-foo  1  -bar 2” is to load them into an array having first
440       loaded in the default settings:
441              array set arguments {-foo 0 -bar 0 -grill 0}
442              array set arguments $::argv
443              puts "foo is $arguments(-foo)"
444              puts "bar is $arguments(-bar)"
445              puts "grill is $arguments(-grill)"
447       The argv0 global variable can be used (in  conjunction  with  the  info
448       script  command)  to determine whether the current script is being exe‐
449       cuted as the main script or  loaded  as  a  library.   This  is  useful
450       because  it  allows  a single script to be used as both a library and a
451       demonstration of that library:
453              if {$::argv0 eq [info script]} {
454                  # running as: tclsh example.tcl
455              } else {
456                  package provide Example 1.0
457              }


460       eval(n), library(n), tclsh(1), tkvars(n), wish(1)


463       arithmetic, bytecode, compiler, error, environment,  POSIX,  precision,
464       subprocess, user, variables
468Tcl                                   8.0                           tclvars(n)