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

NAME

8       Tcl_GetReturnOptions,      Tcl_SetReturnOptions,      Tcl_AddErrorInfo,
9       Tcl_AppendObjToErrorInfo,   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       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
61                                              -errorinfo 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       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
111       return an integer completion code.  These routines also  leave  in  the
112       interpreter  both a result and a dictionary of return options generated
113       by 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
161       allow for a more efficient alternative  that  meshes  better  with  the
162       bytecode 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
174       location 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
181       intended to be machine-readable.  The  first  item  in  the  -errorcode
182       value identifies the class of error that occurred (e.g., POSIX means an
183       error occurred in a POSIX system call)  and  additional  elements  hold
184       additional  pieces  of  information  that depend on the class.  See the
185       manual entry on the errorCode variable for details on the various  for‐
186       mats for 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
192       -errorinfo  value  describing  the command that was being executed when
193       the error occurred.  By the time the error has been passed all the  way
194       back to the application, it will contain a complete trace of the activ‐
195       ity in 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
229       option to NONE.
230
231       The procedure Tcl_SetErrorCode is  also  used  to  set  the  -errorcode
232       return  option. However, it takes one or more strings to record instead
233       of a value. Otherwise, it is similar to Tcl_SetObjErrorCode  in  behav‐
234       ior.
235
236       Tcl_SetErrorCodeVA  is the same as Tcl_SetErrorCode except that instead
237       of taking a variable number of arguments it takes an argument list.
238
239       The procedure Tcl_GetErrorLine is used to read the integer value of the
240       -errorline  return  option  without  the  overhead  of  a  full call to
241       Tcl_GetReturnOptions.  Likewise, Tcl_SetErrorLine sets  the  -errorline
242       return option value.
243
244       Tcl_PosixError  sets  the -errorcode variable after an error in a POSIX
245       kernel call.  It reads the value of the  errno  C  variable  and  calls
246       Tcl_SetErrorCode  to set the -errorcode return option in the POSIX for‐
247       mat.  The caller must previously have called Tcl_SetErrno to set errno;
248       this  is necessary on some platforms (e.g. Windows) where Tcl is linked
249       into an application as a shared library, or when the error occurs in  a
250       dynamically loaded extension. See the manual entry for Tcl_SetErrno for
251       more information.
252
253       Tcl_PosixError returns a  human-readable  diagnostic  message  for  the
254       error  (this is the same value that will appear as the third element in
255       the -errorcode value).  It may be convenient to include this string  as
256       part  of  the  error  message returned to the application in the inter‐
257       preter's result.
258
259       Tcl_LogCommandInfo is invoked after an error occurs in an  interpreter.
260       It  adds information about the command that was being executed when the
261       error occurred to the -errorinfo value,  and  the  line  number  stored
262       internally in the interpreter is set.
263
264       In  older  releases  of Tcl, there was no Tcl_GetReturnOptions routine.
265       In its place, the global Tcl variables errorInfo and errorCode were the
266       only place to retrieve the error information.  Much existing code writ‐
267       ten for older Tcl releases still  access  this  information  via  those
268       global variables.
269
270       It  is  important to realize that while reading from those global vari‐
271       ables remains a supported way to access these return option values,  it
272       is  important not to assume that writing to those global variables will
273       properly set the corresponding return options.  It has long been empha‐
274       sized  in  this manual page that it is important to call the procedures
275       described here rather than setting errorInfo or errorCode directly with
276       Tcl_ObjSetVar2.
277
278       If  the procedure Tcl_ResetResult is called, it clears all of the state
279       of the interpreter associated with  script  evaluation,  including  the
280       entire  return  options  dictionary.  In particular, the -errorinfo and
281       -errorcode options are reset.  If an error had occurred, the  Tcl_Rese‐
282       tResult  call  will  clear  the  error state to make it appear as if no
283       error had occurred after  all.   The  global  variables  errorInfo  and
284       errorCode  are not modified by Tcl_ResetResult so they continue to hold
285       a record of information about the most recent error seen in  an  inter‐
286       preter.
287

SEE ALSO

289       Tcl_DecrRefCount(3),  Tcl_IncrRefCount(3),  Tcl_Interp(3), Tcl_ResetRe‐
290       sult(3), Tcl_SetErrno(3), errorCode(n), errorInfo(n)
291

KEYWORDS

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