2 '\" Copyright (c) 1989-1993 The Regents of the University of California.
3 '\" Copyright (c) 1994-1997 Sun Microsystems, Inc.
5 '\" See the file "license.terms" for information on usage and redistribution
6 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
8 .TH Tcl_AddErrorInfo 3 8.5 Tcl "Tcl Library Procedures"
9 .\" The -*- nroff -*- definitions below are for supplemental macros used
10 .\" in Tcl/Tk manual entries.
12 .\" .AP type name in/out ?indent?
13 .\" Start paragraph describing an argument to a library procedure.
14 .\" type is type of argument (int, etc.), in/out is either "in", "out",
15 .\" or "in/out" to describe whether procedure reads or modifies arg,
16 .\" and indent is equivalent to second arg of .IP (shouldn't ever be
17 .\" needed; use .AS below instead)
20 .\" Give maximum sizes of arguments for setting tab stops. Type and
21 .\" name are examples of largest possible arguments that will be passed
22 .\" to .AP later. If args are omitted, default tab stops are used.
25 .\" Start box enclosure. From here until next .BE, everything will be
26 .\" enclosed in one large box.
29 .\" End of box enclosure.
32 .\" Begin code excerpt.
37 .\" .VS ?version? ?br?
38 .\" Begin vertical sidebar, for use in marking newly-changed parts
39 .\" of man pages. The first argument is ignored and used for recording
40 .\" the version when the .VS was added, so that the sidebars can be
41 .\" found and removed when they reach a certain age. If another argument
42 .\" is present, then a line break is forced before starting the sidebar.
45 .\" End of vertical sidebar.
48 .\" Begin an indented unfilled display.
51 .\" End of indented unfilled display.
54 .\" Start of list of standard options for a Tk widget. The manpage
55 .\" argument defines where to look up the standard options; if
56 .\" omitted, defaults to "options". The options follow on successive
57 .\" lines, in three columns separated by tabs.
60 .\" End of list of standard options for a Tk widget.
62 .\" .OP cmdName dbName dbClass
63 .\" Start of description of a specific option. cmdName gives the
64 .\" option's name as specified in the class command, dbName gives
65 .\" the option's name in the option database, and dbClass gives
66 .\" the option's class in the option database.
69 .\" Print arg1 underlined, then print arg2 normally.
72 .\" Print arg1 in quotes, then arg2 normally (for trailing punctuation).
75 .\" Print an open parenthesis, arg1 in quotes, then arg2 normally
76 .\" (for trailing punctuation) and then a closing parenthesis.
78 .\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages.
82 .\" # Start an argument description
86 . ie !"\\$2"" .TP \\n()Cu
91 \&\\$1 \\fI\\$2\\fP (\\$3)
104 .\" # define tabbing values for .AP
107 .if !"\\$1"" .nr )A \\w'\\$1'u+3n
110 .if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n
111 .nr )C \\n()Bu+\\w'(in/out)'u+2n
113 .AS Tcl_Interp Tcl_CreateInterp in/out
114 .\" # BS - start boxed text
115 .\" # ^y = starting y location
123 .if n \l'\\n(.lu\(ul'
126 .\" # BE - end boxed text (draw box now)
131 .ie n \l'\\n(^lu\(ul'
133 .\" Draw four-sided box normally, but don't draw top of
134 .\" box if the box started on an earlier page.
136 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
139 \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
146 .\" # VS - start vertical sidebar
147 .\" # ^Y = starting y location
148 .\" # ^v = 1 (for troff; for nroff this doesn't matter)
152 .ie n 'mc \s12\(br\s0
155 .\" # VE - end of vertical sidebar
163 \h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n'
170 .\" # Special macro to handle page bottom: finish off current
171 .\" # box/sidebar if in box/sidebar mode, then invoked standard
172 .\" # page bottom macro.
179 .\" Draw three-sided box if this is the box's first page,
180 .\" draw two sides but no top otherwise.
181 .ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
182 .el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
185 .nr ^x \\n(^tu+1v-\\n(^Yu
186 \kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c
199 .\" # DS - begin display
205 .\" # DE - end display
211 .\" # SO - start of list of standard options
213 'ie '\\$1'' .ds So \\fBoptions\\fR
214 'el .ds So \\fB\\$1\\fR
215 .SH "STANDARD OPTIONS"
221 .\" # SE - end of list of standard options
226 See the \\*(So manual entry for details on the standard options.
228 .\" # OP - start of full description for a single option
233 Command-Line Name: \\fB\\$1\\fR
234 Database Name: \\fB\\$2\\fR
235 Database Class: \\fB\\$3\\fR
239 .\" # CS - begin code excerpt
245 .\" # CE - end code excerpt
250 .\" # UL - underline word
254 .\" # QW - apply quotation marks to word
256 .ie '\\*(lq'"' ``\\$1''\\$2
257 .\"" fix emacs highlighting
258 .el \\*(lq\\$1\\*(rq\\$2
260 .\" # PQ - apply parens and quotation marks to word
262 .ie '\\*(lq'"' (``\\$1''\\$2)\\$3
263 .\"" fix emacs highlighting
264 .el (\\*(lq\\$1\\*(rq\\$2)\\$3
266 .\" # QR - quoted range
268 .ie '\\*(lq'"' ``\\$1''\\-``\\$2''\\$3
269 .\"" fix emacs highlighting
270 .el \\*(lq\\$1\\*(rq\\-\\*(lq\\$2\\*(rq\\$3
272 .\" # MT - "empty" string
278 Tcl_GetReturnOptions, Tcl_SetReturnOptions, Tcl_AddErrorInfo, Tcl_AppendObjToErrorInfo, Tcl_AddObjErrorInfo, Tcl_SetObjErrorCode, Tcl_SetErrorCode, Tcl_SetErrorCodeVA, Tcl_SetErrorLine, Tcl_GetErrorLine, Tcl_PosixError, Tcl_LogCommandInfo \- retrieve or record information about errors and other return options
281 \fB#include <tcl.h>\fR
284 \fBTcl_GetReturnOptions\fR(\fIinterp, code\fR)
287 \fBTcl_SetReturnOptions\fR(\fIinterp, options\fR)
289 \fBTcl_AddErrorInfo\fR(\fIinterp, message\fR)
291 \fBTcl_AppendObjToErrorInfo\fR(\fIinterp, objPtr\fR)
293 \fBTcl_AddObjErrorInfo\fR(\fIinterp, message, length\fR)
295 \fBTcl_SetObjErrorCode\fR(\fIinterp, errorObjPtr\fR)
297 \fBTcl_SetErrorCode\fR(\fIinterp, element, element, ... \fB(char *) NULL\fR)
299 \fBTcl_SetErrorCodeVA\fR(\fIinterp, argList\fR)
301 \fBTcl_GetErrorLine\fR(\fIinterp\fR)
303 \fBTcl_SetErrorLine\fR(\fIinterp, lineNum\fR)
306 \fBTcl_PosixError\fR(\fIinterp\fR)
309 \fBTcl_LogCommandInfo\fR(\fIinterp, script, command, commandLength\fR)
311 .AS Tcl_Interp commandLength
312 .AP Tcl_Interp *interp in
313 Interpreter in which to record information.
315 The code returned from script evaluation.
317 A dictionary of return options.
319 For \fBTcl_AddErrorInfo\fR,
320 this is a conventional C string to append to the \fB\-errorinfo\fR return option.
321 For \fBTcl_AddObjErrorInfo\fR,
322 this points to the first byte of an array of \fIlength\fR bytes
323 containing a string to append to the \fB\-errorinfo\fR return option.
324 This byte array may contain embedded null bytes
325 unless \fIlength\fR is negative.
326 .AP Tcl_Obj *objPtr in
327 A message to be appended to the \fB\-errorinfo\fR return option
328 in the form of a Tcl_Obj value.
330 The number of bytes to copy from \fImessage\fR when
331 appending to the \fB\-errorinfo\fR return option.
332 If negative, all bytes up to the first null byte are used.
333 .AP Tcl_Obj *errorObjPtr in
334 The \fB\-errorcode\fR return option will be set to this value.
336 String to record as one element of the \fB\-errorcode\fR return option.
337 Last \fIelement\fR argument must be NULL.
338 .AP va_list argList in
339 An argument list which must have been initialized using
340 \fBva_start\fR, and cleared using \fBva_end\fR.
342 The line number of a script where an error occurred.
343 .AP "const char" *script in
344 Pointer to first character in script containing command (must be <= command)
345 .AP "const char" *command in
346 Pointer to first character in command that generated the error
347 .AP int commandLength in
348 Number of bytes in command; -1 means use all bytes up to first null byte
352 The \fBTcl_SetReturnOptions\fR and \fBTcl_GetReturnOptions\fR
353 routines expose the same capabilities as the \fBreturn\fR and
354 \fBcatch\fR commands, respectively, in the form of a C interface.
356 \fBTcl_GetReturnOptions\fR retrieves the dictionary of return options
357 from an interpreter following a script evaluation.
358 Routines such as \fBTcl_Eval\fR are called to evaluate a
359 script in an interpreter. These routines return an integer
360 completion code. These routines also leave in the interpreter
361 both a result and a dictionary of return options generated
362 by script evaluation. Just as \fBTcl_GetObjResult\fR retrieves
363 the result, \fBTcl_GetReturnOptions\fR retrieves the dictionary
364 of return options. The integer completion code should be
365 passed as the \fIcode\fR argument to \fBTcl_GetReturnOptions\fR
366 so that all required options will be present in the dictionary.
367 Specifically, a \fIcode\fR value of \fBTCL_ERROR\fR will
368 ensure that entries for the keys \fB\-errorinfo\fR,
369 \fB\-errorcode\fR, and \fB\-errorline\fR will appear in the
370 dictionary. Also, the entries for the keys \fB\-code\fR
371 and \fB\-level\fR will be adjusted if necessary to agree
372 with the value of \fIcode\fR. The \fB(Tcl_Obj *)\fR returned
373 by \fBTcl_GetReturnOptions\fR points to an unshared
374 \fBTcl_Obj\fR with reference count of zero. The dictionary
375 may be written to, either adding, removing, or overwriting
376 any entries in it, without the need to check for a shared value.
377 As with any \fBTcl_Obj\fR with reference count of zero, it is up to
378 the caller to arrange for its disposal with \fBTcl_DecrRefCount\fR or
379 to a reference to it via \fBTcl_IncrRefCount\fR (or one of the many
380 functions that call that, notably including \fBTcl_SetObjResult\fR and
381 \fBTcl_SetVar2Ex\fR).
383 A typical usage for \fBTcl_GetReturnOptions\fR is to
384 retrieve the stack trace when script evaluation returns
385 \fBTCL_ERROR\fR, like so:
388 int code = Tcl_Eval(interp, script);
389 if (code == TCL_ERROR) {
390 Tcl_Obj *options = \fBTcl_GetReturnOptions\fR(interp, code);
391 Tcl_Obj *key = Tcl_NewStringObj("-errorinfo", -1);
393 Tcl_IncrRefCount(key);
394 Tcl_DictObjGet(NULL, options, key, &stackTrace);
395 Tcl_DecrRefCount(key);
396 /* Do something with stackTrace */
397 Tcl_DecrRefCount(options);
401 \fBTcl_SetReturnOptions\fR sets the return options
402 of \fIinterp\fR to be \fIoptions\fR. If \fIoptions\fR
403 contains any invalid value for any key, TCL_ERROR will
404 be returned, and the interp result will be set to an
405 appropriate error message. Otherwise, a completion code
406 in agreement with the \fB\-code\fR and \fB\-level\fR
407 keys in \fIoptions\fR will be returned.
409 As an example, Tcl's \fBreturn\fR command itself could
410 be implemented in terms of \fBTcl_SetReturnOptions\fR
414 if ((objc % 2) == 0) { /* explicit result argument */
416 Tcl_SetObjResult(interp, objv[objc]);
418 return \fBTcl_SetReturnOptions\fR(interp, Tcl_NewListObj(objc-1, objv+1));
421 (It is not really implemented that way. Internal access
422 privileges allow for a more efficient alternative that meshes
423 better with the bytecode compiler.)
425 Note that a newly created \fBTcl_Obj\fR may be passed
426 in as the \fIoptions\fR argument without the need to tend
427 to any reference counting. This is analogous to
428 \fBTcl_SetObjResult\fR.
430 While \fBTcl_SetReturnOptions\fR provides a general interface
431 to set any collection of return options, there are a handful
432 of return options that are very frequently used. Most
433 notably the \fB\-errorinfo\fR and \fB\-errorcode\fR return
434 options should be set properly when the command procedure
435 of a command returns \fBTCL_ERROR\fR. The \fB\-errorline\fR
436 return option is also read by commands that evaluate scripts
437 and wish to supply detailed error location information in
438 the stack trace text they append to the \fB\-errorinfo\fR option.
439 Tcl provides several simpler interfaces to more directly set
440 these return options.
442 The \fB\-errorinfo\fR option holds a stack trace of the
443 operations that were in progress when an error occurred,
444 and is intended to be human-readable.
445 The \fB\-errorcode\fR option holds a Tcl list of items that
446 are intended to be machine-readable.
447 The first item in the \fB\-errorcode\fR value identifies the class of
449 (e.g., POSIX means an error occurred in a POSIX system call)
450 and additional elements hold additional pieces
451 of information that depend on the class.
452 See the manual entry on the \fBerrorCode\fR variable for details on the
453 various formats for the \fB\-errorcode\fR option used by Tcl's built-in
456 The \fB\-errorinfo\fR option value is gradually built up as an
457 error unwinds through the nested operations.
458 Each time an error code is returned to \fBTcl_Eval\fR, or
459 any of the routines that performs script evaluation,
460 the procedure \fBTcl_AddErrorInfo\fR is called to add
461 additional text to the \fB\-errorinfo\fR value describing the
462 command that was being executed when the error occurred.
463 By the time the error has been passed all the way back
464 to the application, it will contain a complete trace
465 of the activity in progress when the error occurred.
467 It is sometimes useful to add additional information to
468 the \fB\-errorinfo\fR value beyond what can be supplied automatically
469 by the script evaluation routines.
470 \fBTcl_AddErrorInfo\fR may be used for this purpose:
471 its \fImessage\fR argument is an additional
472 string to be appended to the \fB\-errorinfo\fR option.
473 For example, when an error arises during the \fBsource\fR command,
474 the procedure \fBTcl_AddErrorInfo\fR is called to
475 record the name of the file being processed and the
476 line number on which the error occurred.
477 Likewise, when an error arises during evaluation of a
478 Tcl procedures, the procedure name and line number
479 within the procedure are recorded, and so on.
480 The best time to call \fBTcl_AddErrorInfo\fR is just after
481 a script evaluation routine has returned \fBTCL_ERROR\fR.
482 The value of the \fB\-errorline\fR return option (retrieved
483 via a call to \fBTcl_GetReturnOptions\fR) often makes up
484 a useful part of the \fImessage\fR passed to \fBTcl_AddErrorInfo\fR.
486 \fBTcl_AppendObjToErrorInfo\fR is an alternative interface to the
487 same functionality as \fBTcl_AddErrorInfo\fR. \fBTcl_AppendObjToErrorInfo\fR
488 is called when the string value to be appended to the \fB\-errorinfo\fR option
489 is available as a \fBTcl_Obj\fR instead of as a \fBchar\fR array.
491 \fBTcl_AddObjErrorInfo\fR is nearly identical
492 to \fBTcl_AddErrorInfo\fR, except that it has an additional \fIlength\fR
493 argument. This allows the \fImessage\fR string to contain
494 embedded null bytes. This is essentially never a good idea.
495 If the \fImessage\fR needs to contain the null character \fBU+0000\fR,
496 Tcl's usual internal encoding rules should be used to avoid
497 the need for a null byte. If the \fBTcl_AddObjErrorInfo\fR
498 interface is used at all, it should be with a negative \fIlength\fR value.
500 The procedure \fBTcl_SetObjErrorCode\fR is used to set the
501 \fB\-errorcode\fR return option to the list value \fIerrorObjPtr\fR
502 built up by the caller.
503 \fBTcl_SetObjErrorCode\fR is typically invoked just
504 before returning an error. If an error is
505 returned without calling \fBTcl_SetObjErrorCode\fR or
506 \fBTcl_SetErrorCode\fR the Tcl interpreter automatically sets
507 the \fB\-errorcode\fR return option to \fBNONE\fR.
509 The procedure \fBTcl_SetErrorCode\fR is also used to set the
510 \fB\-errorcode\fR return option. However, it takes one or more strings to
511 record instead of a value. Otherwise, it is similar to
512 \fBTcl_SetObjErrorCode\fR in behavior.
514 \fBTcl_SetErrorCodeVA\fR is the same as \fBTcl_SetErrorCode\fR except that
515 instead of taking a variable number of arguments it takes an argument list.
517 The procedure \fBTcl_GetErrorLine\fR is used to read the integer value
518 of the \fB\-errorline\fR return option without the overhead of a full
519 call to \fBTcl_GetReturnOptions\fR. Likewise, \fBTcl_SetErrorLine\fR
520 sets the \fB\-errorline\fR return option value.
523 sets the \fB\-errorcode\fR variable after an error in a POSIX kernel call.
524 It reads the value of the \fBerrno\fR C variable and calls
525 \fBTcl_SetErrorCode\fR to set the \fB\-errorcode\fR return
526 option in the \fBPOSIX\fR format.
527 The caller must previously have called \fBTcl_SetErrno\fR to set
528 \fBerrno\fR; this is necessary on some platforms (e.g. Windows) where Tcl
529 is linked into an application as a shared library, or when the error
530 occurs in a dynamically loaded extension. See the manual entry for
531 \fBTcl_SetErrno\fR for more information.
533 \fBTcl_PosixError\fR returns a human-readable diagnostic message
535 (this is the same value that will appear as the third element
536 in the \fB\-errorcode\fR value).
537 It may be convenient to include this string as part of the
538 error message returned to the application in
539 the interpreter's result.
541 \fBTcl_LogCommandInfo\fR is invoked after an error occurs in an
542 interpreter. It adds information about the command that was being
543 executed when the error occurred to the \fB\-errorinfo\fR value, and
544 the line number stored internally in the interpreter is set.
546 In older releases of Tcl, there was no \fBTcl_GetReturnOptions\fR
547 routine. In its place, the global Tcl variables \fBerrorInfo\fR
548 and \fBerrorCode\fR were the only place to retrieve the error
549 information. Much existing code written for older Tcl releases
550 still access this information via those global variables.
552 It is important to realize that while reading from those
553 global variables remains a supported way to access these
554 return option values, it is important not to assume that
555 writing to those global variables will properly set the
556 corresponding return options. It has long been emphasized
557 in this manual page that it is important to
558 call the procedures described here rather than
559 setting \fBerrorInfo\fR or \fBerrorCode\fR directly with
560 \fBTcl_ObjSetVar2\fR.
562 If the procedure \fBTcl_ResetResult\fR is called,
563 it clears all of the state of the interpreter associated with
564 script evaluation, including the entire return options dictionary.
565 In particular, the \fB\-errorinfo\fR and \fB\-errorcode\fR options
567 If an error had occurred, the \fBTcl_ResetResult\fR call will
568 clear the error state to make it appear as if no error had
570 The global variables \fBerrorInfo\fR and
571 \fBerrorCode\fR are not modified by \fBTcl_ResetResult\fR
572 so they continue to hold a record of information about the
573 most recent error seen in an interpreter.
575 Tcl_DecrRefCount(3), Tcl_IncrRefCount(3), Tcl_Interp(3), Tcl_ResetResult(3),
576 Tcl_SetErrno(3), errorCode(n), errorInfo(n)
578 error, value, value result, stack, trace, variable
OSDN Git Service
