1Tcl_AddErrorInfo(3) Tcl Library Procedures Tcl_AddErrorInfo(3)
2______________________________________________________________________________
6
8 Tcl_AddObjErrorInfo, Tcl_AddErrorInfo, Tcl_SetObjErrorCode, Tcl_SetEr‐
9 rorCode, Tcl_SetErrorCodeVA, Tcl_PosixError, Tcl_LogCommandInfo -
10 record information about errors
11
13 #include <tcl.h>
14 Tcl_AddObjErrorInfo(interp, message, length)
16 Tcl_AddErrorInfo(interp, message)
18 Tcl_SetObjErrorCode(interp, errorObjPtr)
20 Tcl_SetErrorCode(interp, element, element, ... (char *) NULL)
22 Tcl_SetErrorCodeVA(interp, argList)
24 CONST char *
26 Tcl_PosixError(interp)
27 void
29 Tcl_LogCommandInfo(interp, script, command, commandLength)
30
32 Tcl_Interp *interp (in) Interpreter in which to record infor‐
33 mation.
34 char *message (in) For Tcl_AddObjErrorInfo, this points
36 to the first byte of an array of
37 bytes containing a string to record
38 in the errorInfo variable. This byte
39 array may contain embedded null bytes
40 unless length is negative. For
41 Tcl_AddErrorInfo, this is a conven‐
42 tional C string to record in the
43 errorInfo variable.
44 int length (in) The number of bytes to copy from mes‐
46 sage when setting the errorInfo vari‐
47 able. If negative, all bytes up to
48 the first null byte are used.
49 Tcl_Obj *errorObjPtr(in) This variable errorCode will be set
51 to this value.
52 char *element (in) String to record as one element of
54 errorCode variable. Last element
55 argument must be NULL.
56 va_list argList (in) An argument list which must have been
58 initialized using TCL_VARARGS_START,
59 and cleared using va_end.
60 CONST char *script (in) Pointer to first character in script
62 containing command (must be <= com‐
63 mand)
64 CONST char *command (in) Pointer to first character in command
66 that generated the error
67 int commandLength(in) Number of bytes in command; -1 means
69 use all bytes up to first null byte
70_________________________________________________________________
71
74 These procedures are used to manipulate two Tcl global variables that
75 hold information about errors. The variable errorInfo holds a stack
76 trace of the operations that were in progress when an error occurred,
77 and is intended to be human-readable. The variable errorCode holds a
78 list of items that are intended to be machine-readable. The first item
79 in errorCode identifies the class of error that occurred (e.g. POSIX
80 means an error occurred in a POSIX system call) and additional elements
81 in errorCode hold additional pieces of information that depend on the
82 class. See the Tcl overview manual entry for details on the various
83 formats for errorCode.
84 The errorInfo variable is gradually built up as an error unwinds
86 through the nested operations. Each time an error code is returned to
87 Tcl_EvalObjEx (or Tcl_Eval, which calls Tcl_EvalObjEx) it calls the
88 procedure Tcl_AddObjErrorInfo to add additional text to errorInfo
89 describing the command that was being executed when the error occurred.
90 By the time the error has been passed all the way back to the applica‐
91 tion, it will contain a complete trace of the activity in progress when
92 the error occurred.
93 It is sometimes useful to add additional information to errorInfo
95 beyond what can be supplied automatically by Tcl_EvalObjEx. Tcl_AddOb‐
96 jErrorInfo may be used for this purpose: its message and length argu‐
97 ments describe an additional string to be appended to errorInfo. For
98 example, the source command calls Tcl_AddObjErrorInfo to record the
99 name of the file being processed and the line number on which the error
100 occurred; for Tcl procedures, the procedure name and line number within
101 the procedure are recorded, and so on. The best time to call
102 Tcl_AddObjErrorInfo is just after Tcl_EvalObjEx has returned TCL_ERROR.
103 In calling Tcl_AddObjErrorInfo, you may find it useful to use the
104 errorLine field of the interpreter (see the Tcl_Interp manual entry for
105 details).
106 Tcl_AddErrorInfo resembles Tcl_AddObjErrorInfo but differs in initial‐
108 izing errorInfo from the string value of the interpreter's result if
109 the error is just starting to be logged. It does not use the result as
110 a Tcl object so any embedded null characters in the result will cause
111 information to be lost. It also takes a conventional C string in mes‐
112 sage instead of Tcl_AddObjErrorInfo's counted string.
113 The procedure Tcl_SetObjErrorCode is used to set the errorCode vari‐
115 able. errorObjPtr contains a list object built up by the caller. error‐
116 Code is set to this value. Tcl_SetObjErrorCode is typically invoked
117 just before returning an error in an object command. If an error is
118 returned without calling Tcl_SetObjErrorCode or Tcl_SetErrorCode the
119 Tcl interpreter automatically sets errorCode to NONE.
120 The procedure Tcl_SetErrorCode is also used to set the errorCode vari‐
122 able. However, it takes one or more strings to record instead of an
123 object. Otherwise, it is similar to Tcl_SetObjErrorCode in behavior.
124 Tcl_SetErrorCodeVA is the same as Tcl_SetErrorCode except that instead
126 of taking a variable number of arguments it takes an argument list.
127 Tcl_PosixError sets the errorCode variable after an error in a POSIX
129 kernel call. It reads the value of the errno C variable and calls
130 Tcl_SetErrorCode to set errorCode in the POSIX format. The caller must
131 previously have called Tcl_SetErrno to set errno; this is necessary on
132 some platforms (e.g. Windows) where Tcl is linked into an application
133 as a shared library, or when the error occurs in a dynamically loaded
134 extension. See the manual entry for Tcl_SetErrno for more information.
135 Tcl_PosixError returns a human-readable diagnostic message for the
137 error (this is the same value that will appear as the third element in
138 errorCode). It may be convenient to include this string as part of the
139 error message returned to the application in the interpreter's result.
140 Tcl_LogCommandInfo is invoked after an error occurs in an interpreter.
142 It adds information about the command that was being executed when the
143 error occurred to the errorInfo variable, and the line number stored
144 internally in the interpreter is set. On the first call to Tcl_LogCom‐
145 mandInfo or Tcl_AddObjErrorInfo since an error occurred, the old infor‐
146 mation in errorInfo is deleted.
147 It is important to call the procedures described here rather than set‐
149 ting errorInfo or errorCode directly with Tcl_ObjSetVar2. The reason
150 for this is that the Tcl interpreter keeps information about whether
151 these procedures have been called. For example, the first time
152 Tcl_AddObjErrorInfo is called for an error, it clears the existing
153 value of errorInfo and adds the error message in the interpreter's
154 result to the variable before appending message; in subsequent calls,
155 it just appends the new message. When Tcl_SetErrorCode is called, it
156 sets a flag indicating that errorCode has been set; this allows the Tcl
157 interpreter to set errorCode to NONE if it receives an error return
158 when Tcl_SetErrorCode hasn't been called.
159 If the procedure Tcl_ResetResult is called, it clears all of the state
161 associated with errorInfo and errorCode (but it doesn't actually modify
162 the variables). If an error had occurred, this will clear the error
163 state to make it appear as if no error had occurred after all.
164
167 Tcl_DecrRefCount, Tcl_IncrRefCount, Tcl_Interp, Tcl_ResetResult,
168 Tcl_SetErrno
169
172 error, object, object result, stack, trace, variable
173Tcl 8.0 Tcl_AddErrorInfo(3)