tcl7.6 User Commands - tclvars






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 element of  env  will  remove  the
          corresponding environment variable.  Changes to the env
          array will affect the environment passed to children by
          commands  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 format of the rest of the
          list.  The following formats for errorCode are used  by
          the  Tcl core; individual applications may define addi-
          tional 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 precise  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 determined).

          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 ter-
               minate;  it  will  be  one  of  the names from the
               include  file  signal.h,  such  as  SIGPIPE.   The
               fourth element will be a short human-readable mes-
               sage 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  process's  iden-
               tifier  (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 process'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-readable mes-
               sage 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 consist of a list containing a sin-
               gle element whose contents are NONE.

          POSIX errName msg
               If the first element of errorCode is  POSIX,  then
               the  error  occurred  during  a POSIX kernel 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
               corresponding  to  errName, such as ``no such file
               or directory'' for the ENOENT case.

          To set errorCode, applications should use library  pro-
          cedures such as Tcl_SetErrorCode and Tcl_PosixError, 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  contain
          one or more lines identifying the Tcl commands and pro-
          cedures 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  containing
          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 contains
          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  appropriate directory, then Tcl
          checks several other directories based on a compiled-in
          default location, 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  variable  is
          returned by the info patchlevel command.

     tcl_pkgPath                                                |
          |                                                        |
          This variable holds a list  of  directories  indicating  |
          where  packages  are  normally installed.  It typically  |
          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 application
          is running, such as the name of the  operating  system,
          its  current release number, and the machine's instruc-
          tion 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 addi-
          tional 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  run-
               ning  on  this machine.  On UNIX machines, this is
               the value returned by uname -r.

          platform
               Either windows, macintosh, or unix.  This  identi-
               fies  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 initialization,  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 indicate the
          name of a user-specific TEXT resource  located  in  the
          application  or extension resource forks.  If it is set
          by application-specific initialization,  then  the  Tcl
          startup  code  will  check  for  the  existence of this
          resource and source it if it exists.  For example,  the
          Macintosh  wish  application 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 version of
          Tcl in the form x.y.   Changes  to  x  represent  major
          changes  with probable incompatibilities and changes to
          y represent  small  enhancements  and  bug  fixes  that
          retain backward compatibility.  The value of this vari-
          able is returned by the info tclversion command.



KEYWORDS

     arithmetic, error, environment,  POSIX,  precision,  subpro-
     cess, variables