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.

       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.

       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:

              machine
                     The  instruction  set   executed   by   this
                     machine,  such  as  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  Win95,  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
              If this variable is set, it must contain a  decimal
              number  giving  the number of significant digits to
              include when converting  floating-point  values  to
              strings.  If this variable is not set then 6 digits
              are included.  17 digits is  ``perfect''  for  IEEE
              floating-point  in  that it allows double-precision
              values to be  converted  to  strings  and  back  to
              binary with no loss of precision.

       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_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, error, environment, POSIX, precision,  subpro-
       cess, variables
