AddErrInfo.3
上传用户:rrhhcc
上传日期:2015-12-11
资源大小:54129k
文件大小:8k
源码类别:

通讯编程

开发平台:

Visual C++

  1. '"
  2. '" Copyright (c) 1989-1993 The Regents of the University of California.
  3. '" Copyright (c) 1994-1997 Sun Microsystems, Inc.
  4. '"
  5. '" See the file "license.terms" for information on usage and redistribution
  6. '" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
  7. '" 
  8. '" RCS: @(#) $Id: AddErrInfo.3,v 1.8.2.1 2003/07/18 16:56:24 dgp Exp $
  9. '" 
  10. .so man.macros
  11. .TH Tcl_AddErrorInfo 3 8.0 Tcl "Tcl Library Procedures"
  12. .BS
  13. .SH NAME
  14. Tcl_AddObjErrorInfo, Tcl_AddErrorInfo, Tcl_SetObjErrorCode, Tcl_SetErrorCode, Tcl_SetErrorCodeVA, Tcl_PosixError, Tcl_LogCommandInfo - record information about errors
  15. .SH SYNOPSIS
  16. .nf
  17. fB#include <tcl.h>fR
  18. .sp
  19. fBTcl_AddObjErrorInfofR(fIinterp, message, lengthfR)
  20. .sp
  21. fBTcl_AddErrorInfofR(fIinterp, messagefR)
  22. .sp
  23. fBTcl_SetObjErrorCodefR(fIinterp, errorObjPtrfR)
  24. .sp
  25. fBTcl_SetErrorCodefR(fIinterp, element, element, ... fB(char *) NULLfR)
  26. .sp
  27. fBTcl_SetErrorCodeVAfR(fIinterp, argListfR)
  28. .sp
  29. CONST char *
  30. fBTcl_PosixErrorfR(fIinterpfR)
  31. .sp
  32. void
  33. fBTcl_LogCommandInfofR(fIinterp, script, command, commandLengthfR)
  34. .SH ARGUMENTS
  35. .AS Tcl_Interp *message
  36. .AP Tcl_Interp *interp in
  37. Interpreter in which to record information.
  38. .AP char *message in
  39. For fBTcl_AddObjErrorInfofR,
  40. this points to the first byte of an array of bytes
  41. containing a string to record in the fBerrorInfofR variable.
  42. This byte array may contain embedded null bytes
  43. unless fIlengthfR is negative.
  44. For fBTcl_AddErrorInfofR,
  45. this is a conventional C string to record in the fBerrorInfofR variable.
  46. .AP int length in
  47. The number of bytes to copy from fImessagefR when
  48. setting the fBerrorInfofR variable.
  49. If negative, all bytes up to the first null byte are used.
  50. .AP Tcl_Obj *errorObjPtr in
  51. This variable fBerrorCodefR will be set to this value.
  52. .AP char *element in
  53. String to record as one element of fBerrorCodefR variable.
  54. Last fIelementfR argument must be NULL.
  55. .AP va_list argList in
  56. An argument list which must have been initialized using
  57. fBTCL_VARARGS_STARTfR, and cleared using fBva_endfR.
  58. .AP "CONST char" *script in
  59. Pointer to first character in script containing command (must be <= command)
  60. .AP "CONST char" *command in
  61. Pointer to first character in command that generated the error
  62. .AP int commandLength in
  63. Number of bytes in command; -1 means use all bytes up to first null byte
  64. .BE
  65. .SH DESCRIPTION
  66. .PP
  67. These procedures are used to manipulate two Tcl global variables
  68. that hold information about errors.
  69. The variable fBerrorInfofR holds a stack trace of the
  70. operations that were in progress when an error occurred,
  71. and is intended to be human-readable.
  72. The variable fBerrorCodefR holds a list of items that
  73. are intended to be machine-readable.
  74. The first item in fBerrorCodefR identifies the class of
  75. error that occurred
  76. (e.g. POSIX means an error occurred in a POSIX system call)
  77. and additional elements in fBerrorCodefR hold additional pieces
  78. of information that depend on the class.
  79. See the Tcl overview manual entry for details on the various
  80. formats for fBerrorCodefR.
  81. .PP
  82. The fBerrorInfofR variable is gradually built up as an
  83. error unwinds through the nested operations.
  84. Each time an error code is returned to fBTcl_EvalObjExfR
  85. (or fBTcl_EvalfR, which calls fBTcl_EvalObjExfR)
  86. it calls the procedure fBTcl_AddObjErrorInfofR to add
  87. additional text to fBerrorInfofR describing the
  88. command that was being executed when the error occurred.
  89. By the time the error has been passed all the way back
  90. to the application, it will contain a complete trace
  91. of the activity in progress when the error occurred.
  92. .PP
  93. It is sometimes useful to add additional information to
  94. fBerrorInfofR beyond what can be supplied automatically
  95. by fBTcl_EvalObjExfR.
  96. fBTcl_AddObjErrorInfofR may be used for this purpose:
  97. its fImessagefR and fIlengthfR arguments describe an additional
  98. string to be appended to fBerrorInfofR.
  99. For example, the fBsourcefR command calls fBTcl_AddObjErrorInfofR
  100. to record the name of the file being processed and the
  101. line number on which the error occurred;
  102. for Tcl procedures, the procedure name and line number
  103. within the procedure are recorded, and so on.
  104. The best time to call fBTcl_AddObjErrorInfofR is just after
  105. fBTcl_EvalObjExfR has returned fBTCL_ERRORfR.
  106. In calling fBTcl_AddObjErrorInfofR, you may find it useful to
  107. use the fBerrorLinefR field of the interpreter (see the
  108. fBTcl_InterpfR manual entry for details).
  109. .PP
  110. fBTcl_AddErrorInfofR resembles fBTcl_AddObjErrorInfofR
  111. but differs in initializing fBerrorInfofR from the string
  112. value of the interpreter's result
  113. if the error is just starting to be logged.
  114. It does not use the result as a Tcl object
  115. so any embedded null characters in the result
  116. will cause information to be lost.
  117. It also takes a conventional C string in fImessagefR
  118. instead of fBTcl_AddObjErrorInfofR's counted string.
  119. .PP
  120. The procedure fBTcl_SetObjErrorCodefR is used to set the
  121. fBerrorCodefR variable. fIerrorObjPtrfR contains a list object
  122. built up by the caller. fBerrorCodefR is set to this
  123. value. fBTcl_SetObjErrorCodefR is typically invoked just 
  124. before returning an error in an object command. If an error is
  125. returned without calling fBTcl_SetObjErrorCodefR or
  126. fBTcl_SetErrorCodefR the Tcl interpreter automatically sets
  127. fBerrorCodefR to fBNONEfR.
  128. .PP
  129. The procedure fBTcl_SetErrorCodefR is also used to set the
  130. fBerrorCodefR variable. However, it takes one or more strings to
  131. record instead of an object. Otherwise, it is similar to
  132. fBTcl_SetObjErrorCodefR in behavior.
  133. .PP
  134. fBTcl_SetErrorCodeVAfR is the same as fBTcl_SetErrorCodefR except that
  135. instead of taking a variable number of arguments it takes an argument list.
  136. .PP
  137. fBTcl_PosixErrorfR
  138. sets the fBerrorCodefR variable after an error in a POSIX kernel call.
  139. It reads the value of the fBerrnofR C variable and calls
  140. fBTcl_SetErrorCodefR to set fBerrorCodefR in the fBPOSIXfR format.
  141. The caller must previously have called fBTcl_SetErrnofR to set
  142. fBerrnofR; this is necessary on some platforms (e.g. Windows) where Tcl
  143. is linked into an application as a shared library, or when the error
  144. occurs in a dynamically loaded extension. See the manual entry for
  145. fBTcl_SetErrnofR for more information.
  146. .PP
  147. fBTcl_PosixErrorfR returns a human-readable diagnostic message
  148. for the error
  149. (this is the same value that will appear as the third element
  150. in fBerrorCodefR).
  151. It may be convenient to include this string as part of the
  152. error message returned to the application in
  153. the interpreter's result.
  154. .PP
  155. fBTcl_LogCommandInfofR is invoked after an error occurs in an
  156. interpreter.  It adds information about the command that was being
  157. executed when the error occurred to the fBerrorInfofR variable, and
  158. the line number stored internally in the interpreter is set.  On the
  159. first call to fBTcl_LogCommandInfofR or fBTcl_AddObjErrorInfofR
  160. since an error occurred, the old information in fBerrorInfofR is
  161. deleted.
  162. .PP
  163. It is important to call the procedures described here rather than
  164. setting fBerrorInfofR or fBerrorCodefR directly with
  165. fBTcl_ObjSetVar2fR.
  166. The reason for this is that the Tcl interpreter keeps information
  167. about whether these procedures have been called.
  168. For example, the first time fBTcl_AddObjErrorInfofR is called
  169. for an error, it clears the existing value of fBerrorInfofR
  170. and adds the error message in the interpreter's result to the variable
  171. before appending fImessagefR;
  172. in subsequent calls, it just appends the new fImessagefR.
  173. When fBTcl_SetErrorCodefR is called, it sets a flag indicating
  174. that fBerrorCodefR has been set;
  175. this allows the Tcl interpreter to set fBerrorCodefR to fBNONEfR
  176. if it receives an error return
  177. when fBTcl_SetErrorCodefR hasn't been called.
  178. .PP
  179. If the procedure fBTcl_ResetResultfR is called,
  180. it clears all of the state associated with
  181. fBerrorInfofR and fBerrorCodefR
  182. (but it doesn't actually modify the variables).
  183. If an error had occurred, this will clear the error state to
  184. make it appear as if no error had occurred after all.
  185. .SH "SEE ALSO"
  186. Tcl_DecrRefCount, Tcl_IncrRefCount, Tcl_Interp, Tcl_ResetResult, Tcl_SetErrno
  187. .SH KEYWORDS
  188. error, object, object result, stack, trace, variable