1Tcl_AddErrorInfo(3) Tcl Library Procedures Tcl_AddErrorInfo(3)
2______________________________________________________________________________
6
8 Tcl_GetReturnOptions, Tcl_SetReturnOptions, Tcl_AddErrorInfo, Tcl_Ap‐
9 pendObjToErrorInfo, Tcl_AddObjErrorInfo, Tcl_SetObjErrorCode,
10 Tcl_SetErrorCode, Tcl_SetErrorCodeVA, Tcl_SetErrorLine, Tcl_GetError‐
11 Line, Tcl_PosixError, Tcl_LogCommandInfo - retrieve or record informa‐
12 tion about errors and other return 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 Tcl_GetErrorLine(interp)
36 Tcl_SetErrorLine(interp, lineNum)
38 const char *
40 Tcl_PosixError(interp)
41 void
43 Tcl_LogCommandInfo(interp, script, command, commandLength)
44
46 Tcl_Interp *interp (in) Interpreter in which to record
47 information.
48 int code The code returned from script
50 evaluation.
51 Tcl_Obj *options A dictionary of return options.
53 const char *message (in) For Tcl_AddErrorInfo, this is a
55 conventional C string to append
56 to the -errorinfo return option.
57 For Tcl_AddObjErrorInfo, this
58 points to the first byte of an
59 array of length bytes containing
60 a string to append to the -er‐
61 rorinfo return option. This
62 byte array may contain embedded
63 null bytes unless length is neg‐
64 ative.
65 Tcl_Obj *objPtr (in) A message to be appended to the
67 -errorinfo return option in the
68 form of a Tcl_Obj value.
69 int length (in) The number of bytes to copy from
71 message when appending to the
72 -errorinfo return option. If
73 negative, all bytes up to the
74 first null byte are used.
75 Tcl_Obj *errorObjPtr (in) The -errorcode return option
77 will be set to this value.
78 const char *element (in) String to record as one element
80 of the -errorcode return option.
81 Last element argument must be
82 NULL.
83 va_list argList (in) An argument list which must have
85 been initialized using va_start,
86 and cleared using va_end.
87 int lineNum The line number of a script
89 where an error occurred.
90 const char *script (in) Pointer to first character in
92 script containing command (must
93 be <= command)
94 const char *command (in) Pointer to first character in
96 command that generated the error
97 int commandLength (in) Number of bytes in command; -1
99 means use all bytes up to first
100 null byte
101______________________________________________________________________________
102
104 The Tcl_SetReturnOptions and Tcl_GetReturnOptions routines expose the
105 same capabilities as the return and catch commands, respectively, in
106 the form of a C interface.
107 Tcl_GetReturnOptions retrieves the dictionary of return options from an
109 interpreter following a script evaluation. Routines such as Tcl_Eval
110 are called to evaluate a script in an interpreter. These routines re‐
111 turn an integer completion code. These routines also leave in the in‐
112 terpreter both a result and a dictionary of return options generated by
113 script evaluation. Just as Tcl_GetObjResult retrieves the result,
114 Tcl_GetReturnOptions retrieves the dictionary of return options. The
115 integer completion code should be passed as the code argument to
116 Tcl_GetReturnOptions so that all required options will be present in
117 the dictionary. Specifically, a code value of TCL_ERROR will ensure
118 that entries for the keys -errorinfo, -errorcode, and -errorline will
119 appear in the dictionary. Also, the entries for the keys -code and
120 -level will be adjusted if necessary to agree with the value of code.
121 The (Tcl_Obj *) returned by Tcl_GetReturnOptions points to an unshared
122 Tcl_Obj with reference count of zero. The dictionary may be written
123 to, either adding, removing, or overwriting any entries in it, without
124 the need to check for a shared value. As with any Tcl_Obj with refer‐
125 ence count of zero, it is up to the caller to arrange for its disposal
126 with Tcl_DecrRefCount or to a reference to it via Tcl_IncrRefCount (or
127 one of the many functions that call that, notably including Tcl_SetOb‐
128 jResult and Tcl_SetVar2Ex).
129 A typical usage for Tcl_GetReturnOptions is to retrieve the stack trace
131 when script evaluation returns TCL_ERROR, like so:
132 int code = Tcl_Eval(interp, script);
134 if (code == TCL_ERROR) {
135 Tcl_Obj *options = Tcl_GetReturnOptions(interp, code);
136 Tcl_Obj *key = Tcl_NewStringObj("-errorinfo", -1);
137 Tcl_Obj *stackTrace;
138 Tcl_IncrRefCount(key);
139 Tcl_DictObjGet(NULL, options, key, &stackTrace);
140 Tcl_DecrRefCount(key);
141 /* Do something with stackTrace */
142 Tcl_DecrRefCount(options);
143 }
144 Tcl_SetReturnOptions sets the return options of interp to be options.
146 If options contains any invalid value for any key, TCL_ERROR will be
147 returned, and the interp result will be set to an appropriate error
148 message. Otherwise, a completion code in agreement with the -code and
149 -level keys in options will be returned.
150 As an example, Tcl's return command itself could be implemented in
152 terms of Tcl_SetReturnOptions like so:
153 if ((objc % 2) == 0) { /* explicit result argument */
155 objc--;
156 Tcl_SetObjResult(interp, objv[objc]);
157 }
158 return Tcl_SetReturnOptions(interp, Tcl_NewListObj(objc-1, objv+1));
159 (It is not really implemented that way. Internal access privileges al‐
161 low for a more efficient alternative that meshes better with the byte‐
162 code compiler.)
163 Note that a newly created Tcl_Obj may be passed in as the options argu‐
165 ment without the need to tend to any reference counting. This is anal‐
166 ogous to Tcl_SetObjResult.
167 While Tcl_SetReturnOptions provides a general interface to set any col‐
169 lection of return options, there are a handful of return options that
170 are very frequently used. Most notably the -errorinfo and -errorcode
171 return options should be set properly when the command procedure of a
172 command returns TCL_ERROR. The -errorline return option is also read
173 by commands that evaluate scripts and wish to supply detailed error lo‐
174 cation information in the stack trace text they append to the -error‐
175 info option. Tcl provides several simpler interfaces to more directly
176 set these return options.
177 The -errorinfo option holds a stack trace of the operations that were
179 in progress when an error occurred, and is intended to be human-read‐
180 able. The -errorcode option holds a Tcl list of items that are in‐
181 tended to be machine-readable. The first item in the -errorcode value
182 identifies the class of error that occurred (e.g., POSIX means an error
183 occurred in a POSIX system call) and additional elements hold addi‐
184 tional pieces of information that depend on the class. See the manual
185 entry on the errorCode variable for details on the various formats for
186 the -errorcode option used by Tcl's built-in commands.
187 The -errorinfo option value is gradually built up as an error unwinds
189 through the nested operations. Each time an error code is returned to
190 Tcl_Eval, or any of the routines that performs script evaluation, the
191 procedure Tcl_AddErrorInfo is called to add additional text to the -er‐
192 rorinfo value describing the command that was being executed when the
193 error occurred. By the time the error has been passed all the way back
194 to the application, it will contain a complete trace of the activity in
195 progress when the error occurred.
196 It is sometimes useful to add additional information to the -errorinfo
198 value beyond what can be supplied automatically by the script evalua‐
199 tion routines. Tcl_AddErrorInfo may be used for this purpose: its mes‐
200 sage argument is an additional string to be appended to the -errorinfo
201 option. For example, when an error arises during the source command,
202 the procedure Tcl_AddErrorInfo is called to record the name of the file
203 being processed and the line number on which the error occurred. Like‐
204 wise, when an error arises during evaluation of a Tcl procedures, the
205 procedure name and line number within the procedure are recorded, and
206 so on. The best time to call Tcl_AddErrorInfo is just after a script
207 evaluation routine has returned TCL_ERROR. The value of the -errorline
208 return option (retrieved via a call to Tcl_GetReturnOptions) often
209 makes up a useful part of the message passed to Tcl_AddErrorInfo.
210 Tcl_AppendObjToErrorInfo is an alternative interface to the same func‐
212 tionality as Tcl_AddErrorInfo. Tcl_AppendObjToErrorInfo is called when
213 the string value to be appended to the -errorinfo option is available
214 as a Tcl_Obj instead of as a char array.
215 Tcl_AddObjErrorInfo is nearly identical to Tcl_AddErrorInfo, except
217 that it has an additional length argument. This allows the message
218 string to contain embedded null bytes. This is essentially never a
219 good idea. If the message needs to contain the null character U+0000,
220 Tcl's usual internal encoding rules should be used to avoid the need
221 for a null byte. If the Tcl_AddObjErrorInfo interface is used at all,
222 it should be with a negative length value.
223 The procedure Tcl_SetObjErrorCode is used to set the -errorcode return
225 option to the list value errorObjPtr built up by the caller. Tcl_SetO‐
226 bjErrorCode is typically invoked just before returning an error. If an
227 error is returned without calling Tcl_SetObjErrorCode or Tcl_SetError‐
228 Code the Tcl interpreter automatically sets the -errorcode return op‐
229 tion to NONE.
230 The procedure Tcl_SetErrorCode is also used to set the -errorcode re‐
232 turn option. However, it takes one or more strings to record instead of
233 a value. Otherwise, it is similar to Tcl_SetObjErrorCode in behavior.
234 Tcl_SetErrorCodeVA is the same as Tcl_SetErrorCode except that instead
236 of taking a variable number of arguments it takes an argument list.
237 The procedure Tcl_GetErrorLine is used to read the integer value of the
239 -errorline return option without the overhead of a full call to Tcl_Ge‐
240 tReturnOptions. Likewise, Tcl_SetErrorLine sets the -errorline return
241 option value.
242 Tcl_PosixError sets the -errorcode variable after an error in a POSIX
244 kernel call. It reads the value of the errno C variable and calls
245 Tcl_SetErrorCode to set the -errorcode return option in the POSIX for‐
246 mat. The caller must previously have called Tcl_SetErrno to set errno;
247 this is necessary on some platforms (e.g. Windows) where Tcl is linked
248 into an application as a shared library, or when the error occurs in a
249 dynamically loaded extension. See the manual entry for Tcl_SetErrno for
250 more information.
251 Tcl_PosixError returns a human-readable diagnostic message for the er‐
253 ror (this is the same value that will appear as the third element in
254 the -errorcode value). It may be convenient to include this string as
255 part of the error message returned to the application in the inter‐
256 preter's result.
257 Tcl_LogCommandInfo is invoked after an error occurs in an interpreter.
259 It adds information about the command that was being executed when the
260 error occurred to the -errorinfo value, and the line number stored in‐
261 ternally in the interpreter is set.
262 In older releases of Tcl, there was no Tcl_GetReturnOptions routine.
264 In its place, the global Tcl variables errorInfo and errorCode were the
265 only place to retrieve the error information. Much existing code writ‐
266 ten for older Tcl releases still access this information via those
267 global variables.
268 It is important to realize that while reading from those global vari‐
270 ables remains a supported way to access these return option values, it
271 is important not to assume that writing to those global variables will
272 properly set the corresponding return options. It has long been empha‐
273 sized in this manual page that it is important to call the procedures
274 described here rather than setting errorInfo or errorCode directly with
275 Tcl_ObjSetVar2.
276 If the procedure Tcl_ResetResult is called, it clears all of the state
278 of the interpreter associated with script evaluation, including the en‐
279 tire return options dictionary. In particular, the -errorinfo and -er‐
280 rorcode options are reset. If an error had occurred, the Tcl_ResetRe‐
281 sult call will clear the error state to make it appear as if no error
282 had occurred after all. The global variables errorInfo and errorCode
283 are not modified by Tcl_ResetResult so they continue to hold a record
284 of information about the most recent error seen in an interpreter.
285
287 Tcl_DecrRefCount(3), Tcl_IncrRefCount(3), Tcl_Interp(3), Tcl_ResetRe‐
288 sult(3), Tcl_SetErrno(3), errorCode(n), errorInfo(n)
289
291 error, value, value result, stack, trace, variable
292Tcl 8.5 Tcl_AddErrorInfo(3)