1Tcl_AddErrorInfo(3) Tcl Library Procedures Tcl_AddErrorInfo(3)
2______________________________________________________________________________
6
8 Tcl_GetReturnOptions, Tcl_SetReturnOptions, Tcl_AddErrorInfo,
9 Tcl_AppendObjToErrorInfo, Tcl_AddObjErrorInfo, Tcl_SetObjErrorCode,
10 Tcl_SetErrorCode, Tcl_SetErrorCodeVA, Tcl_PosixError, Tcl_LogCommand‐
11 Info - retrieve or record information about errors and other return
12 options
13
15 #include <tcl.h>
16 Tcl_Obj * │
18 Tcl_GetReturnOptions(interp, code) │
19 int │
21 Tcl_SetReturnOptions(interp, options) │
22 Tcl_AddErrorInfo(interp, message)
24 Tcl_AppendObjToErrorInfo(interp, objPtr) │
26 Tcl_AddObjErrorInfo(interp, message, length)
28 Tcl_SetObjErrorCode(interp, errorObjPtr)
30 Tcl_SetErrorCode(interp, element, element, ... (char *) NULL)
32 Tcl_SetErrorCodeVA(interp, argList)
34 const char *
36 Tcl_PosixError(interp)
37 void
39 Tcl_LogCommandInfo(interp, script, command, commandLength)
40
42 Tcl_Interp *interp (in) Interpreter in which to record
43 information.
44 int code The code returned from script
46 evaluation.
47 Tcl_Obj *options A dictionary of return options.
49 char *message (in) For Tcl_AddErrorInfo, this is a
51 conventional C string to append
52 to the -errorinfo return option.
53 For Tcl_AddObjErrorInfo, this
54 points to the first byte of an
55 array of length bytes containing
56 a string to append to the
57 -errorinfo return option. This
58 byte array may contain embedded
59 null bytes unless length is neg‐
60 ative. │
61 Tcl_Obj *objPtr (in) │
63 A message to be appended to the │
64 -errorinfo return option in the │
65 form of a Tcl_Obj value.
66 int length (in) The number of bytes to copy from
68 message when appending to the
69 -errorinfo return option. If
70 negative, all bytes up to the
71 first null byte are used.
72 Tcl_Obj *errorObjPtr (in) The -errorcode return option
74 will be set to this value.
75 char *element (in) String to record as one element
77 of the -errorcode return option.
78 Last element argument must be
79 NULL.
80 va_list argList (in) An argument list which must have
82 been initialized using va_start,
83 and cleared using va_end.
84 const char *script (in) Pointer to first character in
86 script containing command (must
87 be <= command)
88 const char *command (in) Pointer to first character in
90 command that generated the error
91 int commandLength (in) Number of bytes in command; -1
93 means use all bytes up to first
94 null byte
95_________________________________________________________________
96
99 The Tcl_SetReturnOptions and Tcl_GetReturnOptions routines expose the │
100 same capabilities as the return and catch commands, respectively, in │
101 the form of a C interface. │
102 Tcl_GetReturnOptions retrieves the dictionary of return options from an │
104 interpreter following a script evaluation. Routines such as Tcl_Eval │
105 are called to evaluate a script in an interpreter. These routines │
106 return an integer completion code. These routines also leave in the │
107 interpreter both a result and a dictionary of return options generated │
108 by script evaluation. Just as Tcl_GetObjResult retrieves the result, │
109 Tcl_GetReturnOptions retrieves the dictionary of return options. The │
110 integer completion code should be passed as the code argument to │
111 Tcl_GetReturnOptions so that all required options will be present in │
112 the dictionary. Specifically, a code value of TCL_ERROR will ensure │
113 that entries for the keys -errorinfo, -errorcode, and -errorline will │
114 appear in the dictionary. Also, the entries for the keys -code and │
115 -level will be adjusted if necessary to agree with the value of code. │
116 The (Tcl_Obj *) returned by Tcl_GetReturnOptions points to an unshared │
117 Tcl_Obj with reference count of zero. The dictionary may be written │
118 to, either adding, removing, or overwriting any entries in it, without │
119 the need to check for a shared object. │
120 A typical usage for Tcl_GetReturnOptions is to retrieve the stack trace │
122 when script evaluation returns TCL_ERROR, like so: │
123 int code = Tcl_Eval(interp, script); │
124 if (code == TCL_ERROR) { │
125 Tcl_Obj *options = Tcl_GetReturnOptions(interp, code); │
126 Tcl_Obj *key = Tcl_NewStringObj("-errorinfo", -1); │
127 Tcl_Obj *stackTrace; │
128 Tcl_IncrRefCount(key); │
129 Tcl_DictObjGet(NULL, options, key, &stackTrace); │
130 Tcl_DecrRefCount(key); │
131 /* Do something with stackTrace */ │
132 } │
133 Tcl_SetReturnOptions sets the return options of interp to be options. │
135 If options contains any invalid value for any key, TCL_ERROR will be │
136 returned, and the interp result will be set to an appropriate error │
137 message. Otherwise, a completion code in agreement with the -code and │
138 -level keys in options will be returned. │
139 As an example, Tcl's return command itself could be implemented in │
141 terms of Tcl_SetReturnOptions like so: │
142 if ((objc % 2) == 0) { /* explicit result argument */ │
143 objc--; │
144 Tcl_SetObjResult(interp, objv[objc]); │
145 } │
146 return Tcl_SetReturnOptions(interp, Tcl_NewListObj(objc-1, objv+1));│
147 (It is not really implemented that way. Internal access privileges │
148 allow for a more efficient alternative that meshes better with the │
149 bytecode compiler.) │
150 Note that a newly created Tcl_Obj may be passed in as the options argu‐ │
152 ment without the need to tend to any reference counting. This is anal‐ │
153 ogous to Tcl_SetObjResult. │
154 While Tcl_SetReturnOptions provides a general interface to set any col‐ │
156 lection of return options, there are a handful of return options that │
157 are very frequently used. Most notably the -errorinfo and -errorcode │
158 return options should be set properly when the command procedure of a │
159 command returns TCL_ERROR. Tcl provides several simpler interfaces to │
160 more directly set these return options.
161 The -errorinfo option holds a stack trace of the operations that were
163 in progress when an error occurred, and is intended to be human-read‐
164 able. The -errorcode option holds a list of items that are intended to
165 be machine-readable. The first item in the -errorcode value identifies
166 the class of error that occurred (e.g. POSIX means an error occurred in
167 a POSIX system call) and additional elements hold additional pieces of
168 information that depend on the class. See the tclvars manual entry for
169 details on the various formats for the -errorcode option used by Tcl's
170 built-in commands.
171 The -errorinfo option value is gradually built up as an error unwinds
173 through the nested operations. Each time an error code is returned to
174 Tcl_Eval, or any of the routines that performs script evaluation, the
175 procedure Tcl_AddErrorInfo is called to add additional text to the
176 -errorinfo value describing the command that was being executed when
177 the error occurred. By the time the error has been passed all the way
178 back to the application, it will contain a complete trace of the activ‐
179 ity in progress when the error occurred.
180 It is sometimes useful to add additional information to the -errorinfo
182 value beyond what can be supplied automatically by the script evalua‐
183 tion routines. Tcl_AddErrorInfo may be used for this purpose: its mes‐
184 sage argument is an additional string to be appended to the -errorinfo
185 option. For example, when an error arises during the source command,
186 the procedure Tcl_AddErrorInfo is called to record the name of the file
187 being processed and the line number on which the error occurred. Like‐
188 wise, when an error arises during evaluation of a Tcl procedures, the
189 procedure name and line number within the procedure are recorded, and
190 so on. The best time to call Tcl_AddErrorInfo is just after a script
191 evaluation routine has returned TCL_ERROR. The value of the -errorline
192 return option (retrieved via a call to Tcl_GetReturnOptions) often
193 makes up a useful part of the message passed to Tcl_AddErrorInfo.
194 Tcl_AppendObjToErrorInfo is an alternative interface to the same func‐ │
196 tionality as Tcl_AddErrorInfo. Tcl_AppendObjToErrorInfo is called when │
197 the string value to be appended to the -errorinfo option is available │
198 as a Tcl_Obj instead of as a char array.
199 Tcl_AddObjErrorInfo is nearly identical to Tcl_AddErrorInfo, except
201 that it has an additional length argument. This allows the message
202 string to contain embedded null bytes. This is essentially never a
203 good idea. If the message needs to contain the null character U+0000,
204 Tcl's usual internal encoding rules should be used to avoid the need
205 for a null byte. If the Tcl_AddObjErrorInfo interface is used at all,
206 it should be with a negative length value.
207 The procedure Tcl_SetObjErrorCode is used to set the -errorcode return
209 option to the list object errorObjPtr built up by the caller.
210 Tcl_SetObjErrorCode is typically invoked just before returning an
211 error. If an error is returned without calling Tcl_SetObjErrorCode or
212 Tcl_SetErrorCode the Tcl interpreter automatically sets the -errorcode
213 return option to NONE.
214 The procedure Tcl_SetErrorCode is also used to set the -errorcode
216 return option. However, it takes one or more strings to record instead
217 of an object. Otherwise, it is similar to Tcl_SetObjErrorCode in behav‐
218 ior.
219 Tcl_SetErrorCodeVA is the same as Tcl_SetErrorCode except that instead
221 of taking a variable number of arguments it takes an argument list.
222 Tcl_PosixError sets the -errorcode variable after an error in a POSIX
224 kernel call. It reads the value of the errno C variable and calls
225 Tcl_SetErrorCode to set the -errorcode return option in the POSIX for‐
226 mat. The caller must previously have called Tcl_SetErrno to set errno;
227 this is necessary on some platforms (e.g. Windows) where Tcl is linked
228 into an application as a shared library, or when the error occurs in a
229 dynamically loaded extension. See the manual entry for Tcl_SetErrno for
230 more information.
231 Tcl_PosixError returns a human-readable diagnostic message for the
233 error (this is the same value that will appear as the third element in
234 the -errorcode value). It may be convenient to include this string as
235 part of the error message returned to the application in the inter‐
236 preter's result.
237 Tcl_LogCommandInfo is invoked after an error occurs in an interpreter.
239 It adds information about the command that was being executed when the
240 error occurred to the -errorinfo value, and the line number stored
241 internally in the interpreter is set.
242 In older releases of Tcl, there was no Tcl_GetReturnOptions routine.
244 In its place, the global Tcl variables errorInfo and errorCode were the
245 only place to retrieve the error information. Much existing code writ‐
246 ten for older Tcl releases still access this information via those
247 global variables.
248 It is important to realize that while reading from those global vari‐
250 ables remains a supported way to access these return option values, it
251 is important not to assume that writing to those global variables will
252 properly set the corresponding return options. It has long been empha‐
253 sized in this manual page that it is important to call the procedures
254 described here rather than setting errorInfo or errorCode directly with
255 Tcl_ObjSetVar2.
256 If the procedure Tcl_ResetResult is called, it clears all of the state
258 of the interpreter associated with script evaluation, including the
259 entire return options dictionary. In particular, the -errorinfo and
260 -errorcode options are reset. If an error had occurred, the Tcl_Rese‐
261 tResult call will clear the error state to make it appear as if no
262 error had occurred after all. The global variables errorInfo and
263 errorCode are not modified by Tcl_ResetResult so they continue to hold
264 a record of information about the most recent error seen in an inter‐
265 preter.
266
269 Tcl_DecrRefCount, Tcl_IncrRefCount, Tcl_Interp, Tcl_ResetResult,
270 Tcl_SetErrno
271
274 error, object, object result, stack, trace, variable
275Tcl 8.5 Tcl_AddErrorInfo(3)