home *** CD-ROM | disk | FTP | other *** search
/ InfoMagic Source Code 1993 July / THE_SOURCE_CODE_CD_ROM.iso / languages / tcl / tcl7.0b1 / doc / tclvars.n < prev    next >
Encoding:
Text File  |  1993-06-16  |  6.3 KB  |  157 lines
  1. '\"
  2. '\" Copyright (c) 1993 The Regents of the University of California.
  3. '\" All rights reserved.
  4. '\"
  5. '\" Permission is hereby granted, without written agreement and without
  6. '\" license or royalty fees, to use, copy, modify, and distribute this
  7. '\" documentation for any purpose, provided that the above copyright
  8. '\" notice and the following two paragraphs appear in all copies.
  9. '\"
  10. '\" IN NO EVENT SHALL THE UNIVERSITY OF CALIFORNIA BE LIABLE TO ANY PARTY
  11. '\" FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES
  12. '\" ARISING OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF THE UNIVERSITY OF
  13. '\" CALIFORNIA HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  14. '\"
  15. '\" THE UNIVERSITY OF CALIFORNIA SPECIFICALLY DISCLAIMS ANY WARRANTIES,
  16. '\" INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY
  17. '\" AND FITNESS FOR A PARTICULAR PURPOSE.  THE SOFTWARE PROVIDED HEREUNDER IS
  18. '\" ON AN "AS IS" BASIS, AND THE UNIVERSITY OF CALIFORNIA HAS NO OBLIGATION TO
  19. '\" PROVIDE MAINTENANCE, SUPPORT, UPDATES, ENHANCEMENTS, OR MODIFICATIONS.
  20. '\" 
  21. '\" $Header: /user6/ouster/tcl/man/RCS/tclvars.n,v 1.1 93/06/16 16:52:49 ouster Exp $ SPRITE (Berkeley)
  22. '\" 
  23. .so man.macros
  24. .HS tclvars tcl
  25. .BS
  26. '\" Note:  do not modify the .SH NAME line immediately below!
  27. .SH NAME
  28. tclvars \- Variables used by Tcl
  29. .BE
  30.  
  31. .SH DESCRIPTION
  32. .PP
  33. The following global variables are created and managed automatically
  34. by the Tcl library.  Except where noted below, these variables should
  35. normally be treated as read-only by application-specific code and by users.
  36. .TP
  37. \fBenv\fR
  38. .br
  39. This variable is maintained by Tcl as an array
  40. whose elements are the environment variables for the process.
  41. Reading an element will return the value of the corresponding
  42. environment variable.
  43. Setting an element of the array will modify the corresponding
  44. environment variable or create a new one if it doesn't already
  45. exist.
  46. Unsetting an element of \fBenv\fR will remove the corresponding
  47. environment variable.
  48. Changes to the \fBenv\fR array will affect the environment
  49. passed to children by commands like \fBexec\fR.
  50. If the entire \fBenv\fR array is unset then Tcl will stop
  51. monitoring \fBenv\fR accesses and will not update environment
  52. variables.
  53. .TP
  54. \fBerrorCode\fR
  55. After an error has occurred, this variable will be set to hold
  56. additional information about the error in a form that is easy
  57. to process with programs.
  58. \fBerrorCode\fR consists of a Tcl list with one or more elements.
  59. The first element of the list identifies a general class of
  60. errors, and determines the format of the rest of the list.
  61. The following formats for \fBerrorCode\fR are used by the
  62. Tcl core; individual applications may define additional formats.
  63. .RS
  64. .TP
  65. \fBARITH\fI code msg\fR
  66. .VS
  67. This format is used when an arithmetic error occurs (e.g. an attempt
  68. to divide by zero in the \fBexpr\fR command).
  69. \fICode\fR identifies the precise error and \fImsg\fR provides a
  70. human-readable description of the error.  \fICode\fR will be either
  71. DIVZERO (for an attempt to divide by zero),
  72. DOMAIN (if an argument is outside the domain of a function, such as acos(\-3)),
  73. IOVERFLOW (for integer overflow),
  74. OVERLFLOW (for a floating-point overflow),
  75. or UNKNOWN (if the cause of the error cannot be determined).
  76. .VE
  77. .TP
  78. \fBCHILDKILLED\fI pid sigName msg\fR
  79. This format is used when a child process has been killed because of
  80. a signal.  The second element of \fBerrorCode\fR will be the
  81. process's identifier (in decimal).
  82. The third element will be the symbolic name of the signal that caused
  83. the process to terminate; it will be one of the names from the
  84. include file signal.h, such as \fBSIGPIPE\fR.
  85. The fourth element will be a short human-readable message
  86. describing the signal, such as ``write on pipe with no readers''
  87. for \fBSIGPIPE\fR.
  88. .TP
  89. \fBCHILDSTATUS\fI pid code\fR
  90. This format is used when a child process has exited with a non-zero
  91. exit status.  The second element of \fBerrorCode\fR will be the
  92. process's identifier (in decimal) and the third element will be the exit
  93. code returned by the process (also in decimal).
  94. .TP
  95. \fBCHILDSUSP\fI pid sigName msg\fR
  96. This format is used when a child process has been suspended because
  97. of a signal.
  98. The second element of \fBerrorCode\fR will be the process's identifier,
  99. in decimal.
  100. The third element will be the symbolic name of the signal that caused
  101. the process to suspend; this will be one of the names from the
  102. include file signal.h, such as \fBSIGTTIN\fR.
  103. The fourth element will be a short human-readable message
  104. describing the signal, such as ``background tty read''
  105. for \fBSIGTTIN\fR.
  106. .TP
  107. \fBNONE\fR
  108. .br
  109. This format is used for errors where no additional information is
  110. available for an error besides the message returned with the
  111. error.  In these cases \fBerrorCode\fR will consist of a list
  112. containing a single element whose contents are \fBNONE\fR.
  113. .TP
  114. \fBPOSIX \fIerrName msg\fR
  115. .VS
  116. If the first element of \fBerrorCode\fR is \fBPOSIX\fR, then
  117. the error occurred during a POSIX kernel call.
  118. .VE
  119. The second element of the list will contain the symbolic name
  120. of the error that occurred, such as \fBENOENT\fR; this will
  121. be one of the values defined in the include file errno.h.
  122. The third element of the list will be a human-readable
  123. message corresponding to \fIerrName\fR, such as
  124. ``no such file or directory'' for the \fBENOENT\fR case.
  125. .PP
  126. To set \fBerrorCode\fR, applications should use library
  127. procedures such as \fBTcl_SetErrorCode\fR and
  128. .VS
  129. \fBTcl_PosixError\fR,
  130. .VE
  131. or they may invoke the \fBerror\fR command.
  132. If one of these methods hasn't been used, then the Tcl
  133. interpreter will reset the variable to \fBNONE\fR after
  134. the next error.
  135. .RE
  136. .TP
  137. \fBerrorInfo\fR
  138. After an error has occurred, this string will contain one or more lines
  139. identifying the Tcl commands and procedures that were being executed
  140. when the most recent error occurred.
  141. Its contents take the form of a stack trace showing the various
  142. nested Tcl commands that had been invoked at the time of the error.
  143. .TP
  144. \fBtcl_precision\fR
  145. .VS
  146. If this variable is set, it must contain a decimal number giving the
  147. number of significant digits to include when converting floating-point
  148. values to strings.
  149. If this variable is not set then 6 digits are included.
  150. 17 digits is ``perfect'' for IEEE floating-point in that it allows
  151. double-precision values to be converted to strings and back to
  152. binary with no loss of precision.
  153. .VE
  154.  
  155. .SH KEYWORDS
  156. arithmetic, error, environment, POSIX, precision, subprocess, variables
  157.