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       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
50              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
61                     Detection of these errors depends in part on the underly‐
62                     ing hardware and system libraries.
63
64              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
75              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
82              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
92              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
98              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
107              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
114       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
123       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
144       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
151       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
169       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
179              byteOrder
180                     The  native  byte order of this machine: either littleEn‐
181                     dian or bigEndian.
182
183              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
190              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
195              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
203              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
209              platform
210                     Either windows, or unix.   This  identifies  the  general
211                     operating environment of the machine.
212
213              threaded
214                     If  this  variable  exists, then the interpreter was com‐
215                     piled with threads enabled.
216
217              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
222              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
227              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
232       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
238              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
246              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
253              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
258       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
266       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
277              This  variable and functionality only exist if TCL_COMPILE_DEBUG
278              was defined during Tcl's compilation.
279
280       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
295              This variable and functionality only exist if  TCL_COMPILE_DEBUG
296              was defined during Tcl's compilation.
297
298       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
307       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
316       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

OTHER GLOBAL VARIABLES

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
329       argc  The number of arguments to tclsh or wish.
330
331       argv  Tcl list of arguments to tclsh or wish.
332
333       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
336       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
341       The  wish  executable additionally specifies the following global vari‐
342       able:
343
344       geometry
345             If set, contains the user-supplied geometry specification to  use
346             for the main Tk window.
347

SEE ALSO

349       eval(n), tclsh(1), wish(1)
350

KEYWORDS

352       arithmetic,  bytecode,  compiler, error, environment, POSIX, precision,
353       subprocess, variables
354
355
356
357Tcl                                   8.0                           tclvars(n)
Impressum