1Tcl_AddErrorInfo(3)         Tcl Library Procedures         Tcl_AddErrorInfo(3)
2
3
4
5______________________________________________________________________________
6

NAME

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

SYNOPSIS

15       #include <tcl.h>
16
17       Tcl_Obj *
18       Tcl_GetReturnOptions(interp, code)
19
20       int
21       Tcl_SetReturnOptions(interp, options)
22
23       Tcl_AddErrorInfo(interp, message)
24
25       Tcl_AppendObjToErrorInfo(interp, objPtr)
26
27       Tcl_AddObjErrorInfo(interp, message, length)
28
29       Tcl_SetObjErrorCode(interp, errorObjPtr)
30
31       Tcl_SetErrorCode(interp, element, element, ... (char *) NULL)
32
33       Tcl_SetErrorCodeVA(interp, argList)
34
35       Tcl_GetErrorLine(interp)
36
37       Tcl_SetErrorLine(interp, lineNum)
38
39       const char *
40       Tcl_PosixError(interp)
41
42       void
43       Tcl_LogCommandInfo(interp, script, command, commandLength)
44

ARGUMENTS

46       Tcl_Interp *interp (in)                Interpreter  in  which to record
47                                              information.
48
49       int          code                      The code  returned  from  script
50                                              evaluation.
51
52       Tcl_Obj      *options                  A dictionary of return options.
53
54       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
66       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
70       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
76       Tcl_Obj *errorObjPtr (in)              The   -errorcode  return  option
77                                              will be set to this value.
78
79       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
84       va_list argList (in)                   An argument list which must have
85                                              been initialized using va_start,
86                                              and cleared using va_end.
87
88       int          lineNum                   The  line  number  of  a  script
89                                              where an error occurred.
90
91       const char *script (in)                Pointer to  first  character  in
92                                              script  containing command (must
93                                              be <= command)
94
95       const char *command (in)               Pointer to  first  character  in
96                                              command that generated the error
97
98       int commandLength (in)                 Number  of  bytes in command; -1
99                                              means use all bytes up to  first
100                                              null byte
101______________________________________________________________________________
102

DESCRIPTION

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
108       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
130       A typical usage for Tcl_GetReturnOptions is to retrieve the stack trace
131       when script evaluation returns TCL_ERROR, like so:
132
133              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
145       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
151       As an example, Tcl's return command  itself  could  be  implemented  in
152       terms of Tcl_SetReturnOptions like so:
153
154              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
160       (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
164       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
168       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
178       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
188       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
197       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
211       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
216       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
224       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
231       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
235       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
238       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
243       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
252       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
258       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
263       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
269       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
277       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

SEE ALSO

287       Tcl_DecrRefCount(3),  Tcl_IncrRefCount(3),  Tcl_Interp(3), Tcl_ResetRe‐
288       sult(3), Tcl_SetErrno(3), errorCode(n), errorInfo(n)
289

KEYWORDS

291       error, value, value result, stack, trace, variable
292
293
294
295Tcl                                   8.5                  Tcl_AddErrorInfo(3)
Impressum