NAME
       tclvars - Variables used by Tcl


DESCRIPTION
       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.

       env    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 doesn't already exist.  Unsetting an ele-
              ment  of env will remove the corresponding environ-
              ment variable.   Changes  to  the  env  array  will
              affect  the  environment passed to children by com-
              mands like exec.  If the entire env array is  unset
              then Tcl will stop monitoring env accesses and will
              not update environment variables.
              Under Windows, the environment variables  PATH  and
              COMSPEC  in  any capitalization are converted auto-
              matically to upper case.  For  instance,  the  PATH
              variable  could be exported by the operating system
              as ``path'', ``Path'', ``PaTh'', etc., causing oth-
              erwise simple Tcl code to have to support many spe-
              cial cases.  All other environment variables inher-
              ited by Tcl are left unmodified.
              On  the Macintosh, the environment variable is con-
              structed by Tcl as no global  environment  variable
              exists.  The environment variables that are created
              for Tcl include:

              LOGIN  This holds the Chooser name  of  the  Macin-
                     tosh.

              USER   This also holds the Chooser name of the Mac-
                     intosh.

              SYS_FOLDER
                     The path to the system directory.

              APPLE_M_FOLDER
                     The path to the Apple Menu directory.

              CP_FOLDER
                     The path to the control panels directory.

              DESK_FOLDER
                     The path to the desk top directory.
              EXT_FOLDER
                     The path to the system extensions directory.

              PREF_FOLDER
                     The path to the preferences directory.

              PRINT_MON_FOLDER
                     The path to the print monitor directory.

              SHARED_TRASH_FOLDER
                     The path to the network trash directory.

              TRASH_FOLDER
                     The path to the trash directory.

              START_UP_FOLDER
                     The path to the start up directory.

              PWD    The path to the application's default direc-
                     tory.

              You can also create your own environment  variables
              for  the  Macintosh.  A file named  Tcl Environment
              Variables may be placed in the  preferences  folder
              in  the  Mac system folder.  Each line of this file
              should be of the form VAR_NAME=var_data.

              The last alternative is to place environment  vari-
              ables  in  a  'STR#' resource named Tcl Environment
              Variables of the application.  This is considered a
              little more ``Mac like'' than a Unix style Environ-
              ment Variable  file.   Each  entry  in  the  'STR#'
              resource  has the same format as above.  The source
              code file tclMacEnv.c contains  the  implementation
              of  the  env  mechanisms.   This file contains many
              #define's that allow customization of the env mech-
              anisms to fit your applications needs.

       errorCode
              After  an error has occurred, this variable will be
              set to hold additional information about the  error
              in  a  form  that is easy to process with programs.
              errorCode consists of a Tcl list with one  or  more
              elements.  The first element of the list identifies
              a general class of errors, and determines the  for-
              mat of the rest of the list.  The following formats
              for errorCode are used by the Tcl core;  individual
              applications may define additional formats.

              ARITH code msg
                     This format is used when an arithmetic error
                     occurs (e.g. an attempt to divide by zero in
                     the expr command).  Code identifies the pre-
                     cise error and msg provides a human-readable
                     description  of  the  error.   Code  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 deter-
                     mined).

              CHILDKILLED pid sigName msg
                     This format is used when a child process has
                     been killed because of a signal.  The second
                     element of errorCode will be  the  process's
                     identifier  (in decimal).  The third 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  sig-
                     nal.h,  such as SIGPIPE.  The fourth element
                     will  be  a  short  human-readable   message
                     describing  the  signal,  such as ``write on
                     pipe with no readers'' for SIGPIPE.

              CHILDSTATUS pid code
                     This format is used when a child process has
                     exited  with  a  non-zero  exit status.  The
                     second element of errorCode will be the pro-
                     cess's identifier (in decimal) and the third
                     element will be the exit  code  returned  by
                     the process (also in decimal).

              CHILDSUSP pid sigName msg
                     This format is used when a child process has
                     been suspended because  of  a  signal.   The
                     second element of errorCode will be the pro-
                     cess's identifier, in  decimal.   The  third
                     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 SIGTTIN.  The
                     fourth  element  will be a short human-read-
                     able message describing the signal, such  as
                     ``background tty read'' for SIGTTIN.

              NONE   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 errorCode  will  con-
                     sist  of  a list containing a single element
                     whose contents are NONE.

              POSIX errName msg
                     If the first element of errorCode is  POSIX,
                     then  the error occurred during a POSIX ker-
                     nel call.  The second element  of  the  list
                     will  contain the symbolic name of the error
                     that occurred, such as ENOENT; this will  be
                     one  of  the  values  defined in the include
                     file errno.h.  The third element of the list
                     will be a human-readable message correspond-
                     ing to errName, such as ``no  such  file  or
                     directory'' for the ENOENT case.

              To  set  errorCode, applications should use library
              procedures such as Tcl_SetErrorCode and  Tcl_Posix-
              Error,  or  they  may invoke the error command.  If
              one of these methods hasn't been used, then the Tcl
              interpreter  will  reset the variable to NONE after
              the next error.

       errorInfo
              After an error has occurred, this string will  con-
              tain 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.

       tcl_library
              This variable holds the name of  a  directory  con-
              taining  the system library of Tcl scripts, such as
              those used for auto-loading.   The  value  of  this
              variable  is  returned by the info library command.
              See the library 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 $app_library
              (where app is the application's name) to  hold  the
              network  file  name  for that application's library
              directory.  The initial value of tcl_library is set
              when an interpreter is created by searching several
              different directories until one is found that  con-
              tains  an  appropriate  Tcl startup script.  If the
              TCL_LIBRARY environment variable exists,  then  the
              directory   it   names   is   checked   first.   If
              TCL_LIBRARY isn't set or doesn't refer to an appro-
              priate  directory,  then  Tcl  checks several other
              directories based on a  compiled-in  default  loca-
              tion,  the  location  of  the binary containing the
              application, and the current working directory.

       tcl_patchLevel
              When an interpreter is created Tcl initializes this
              variable  to hold a string giving the current patch
              level for Tcl, such as 7.3p2 for Tcl 7.3  with  the
              first two official patches, or 7.4b4 for the fourth
              beta release of Tcl 7.4.  The value of  this  vari-
              able is returned by the info patchlevel command.

       tcl_pkgPath
              This  variable holds a list of directories indicat-
              ing where packages are normally installed.  It typ-
              ically  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 $tcl_pkgPath. The  directories  in  $tcl_pkgPath
              are  included by default in the auto_path variable,
              so they  and  their  immediate  subdirectories  are
              automatically  searched for packages during package
              require  commands.   Note:   tcl_pkgPath   it   not
              intended  to  be  modified by the application.  Its
              value is added to auto_path at startup; changes  to
              tcl_pkgPath are not reflected in auto_path.  If you
              want Tcl to search additional directories for pack-
              ages  you should add the names of those directories
              to auto_path, not tcl_pkgPath.

       tcl_platform
              This is an associative array whose elements contain
              information  about the platform on which the appli-
              cation is running, such as the name of the  operat-
              ing  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  couldn't  retrieve
              any  relevant information.  In addition, extensions
              and applications may add additional values  to  the
              array.  The predefined elements are:

              byteOrder
                     The  native  byte  order  of  this  machine:
                     either littleEndian or bigEndian.

              machine
                     The  instruction  set   executed   by   this
                     machine,  such as intel, PPC, 68k, or sun4m.
                     On UNIX machines, this is the value returned
                     by uname -m.

              os     The  name of the operating system running on
                     this machine, such as  Win32s,  Windows  NT,
                     MacOS,  or SunOS.  On UNIX machines, this is
                     the value returned by uname -s.

              osVersion
                     The version number for the operating  system
                     running  on this machine.  On UNIX machines,
                     this is the value returned by uname -r.

              platform
                     Either windows, macintosh,  or  unix.   This
                     identifies the general operating environment
                     of the machine.

       tcl_precision
              This variable controls the number of digits to gen-
              erate  when  converting  floating-point  values  to
              strings.  It defaults to 12.  17 digits  is  ``per-
              fect''  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.
              However, using 17  digits  prevents  any  rounding,
              which produces longer, less intuitive results.  For
              example, expr 1.4 returns  1.3999999999999999  with
              tcl_precision  set  to 17, vs. 1.4 if tcl_precision
              is 12.
              All  interpreters  in  a  process  share  a  single
              tcl_precision value: changing it in one interpreter
              will affect all other interpreters as  well.   How-
              ever,  safe  interpreters are not allowed to modify
              the variable.

       tcl_rcFileName
              This variable  is  used  during  initialization  to
              indicate  the name of a user-specific startup file.
              If it is set  by  application-specific  initializa-
              tion,  then the Tcl startup code will check for the
              existence of this file and source it if it  exists.
              For  example,  for  wish  the  variable  is  set to
              ~/.wishrc for Unix and ~/wishrc.tcl for Windows.

       tcl_rcRsrcName
              This variable is only used  on  Macintosh  systems.
              The variable is used during initialization to indi-
              cate the name  of  a  user-specific  TEXT  resource
              located  in  the  application or extension resource
              forks.  If it is set by  application-specific  ini-
              tialization,  then  the Tcl startup code will check
              for the existence of this resource and source it if
              it  exists.  For example, the Macintosh wish appli-
              cation has the variable is set to tclshrc.

       tcl_traceCompile
              The value of this variable can be  set  to  control
              how  much  tracing  information is displayed during
              bytecode compilation.  By default, tcl_traceCompile
              is  zero  and no information is displayed.  Setting
              tcl_traceCompile to 1 generates a one line  summary
              in stdout whenever a procedure or top level command
              is compiled.  Setting it to 2 generates a  detailed
              listing  in  stdout  of  the  bytecode instructions
              emitted during every compilation.  This variable is
              useful in tracking down suspected problems with the
              Tcl compiler.  It is also occasionally useful  when
              converting existing code to use Tcl8.0.

       tcl_traceExec
              The  value  of  this variable can be set to control
              how much tracing information  is  displayed  during
              bytecode  execution.   By default, tcl_traceExec is
              zero and  no  information  is  displayed.   Setting
              tcl_traceExec  to  1  generates a one line trace in
              stdout 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 pro-
              duces a detailed trace showing the result  of  exe-
              cuting  each  bytecode instruction.  Note that when
              tcl_traceExec is 2 or 3, commands such as  set  and
              incr 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  inter-
              preter.   It  is also occasionally useful when con-
              verting code to use Tcl8.0.

       tcl_version
              When an interpreter is created Tcl initializes this
              variable  to  hold the version number for this ver-
              sion of Tcl in the form x.y.  Changes to  x  repre-
              sent  major changes with probable incompatibilities
              and changes to y represent small  enhancements  and
              bug  fixes that retain backward compatibility.  The
              value of this variable  is  returned  by  the  info
              tclversion command.


KEYWORDS
       arithmetic, bytecode, compiler, error, environment, POSIX,
       precision, subprocess, variables
