diff options
Diffstat (limited to 'doc/AddErrInfo.3')
| -rw-r--r-- | doc/AddErrInfo.3 | 150 |
1 files changed, 88 insertions, 62 deletions
diff --git a/doc/AddErrInfo.3 b/doc/AddErrInfo.3 index bc32cd1..0b59349 100644 --- a/doc/AddErrInfo.3 +++ b/doc/AddErrInfo.3 @@ -4,28 +4,26 @@ '\" '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" -'\" RCS: @(#) $Id: AddErrInfo.3,v 1.15 2005/09/13 21:23:51 dgp Exp $ -'\" -.so man.macros +'\" .TH Tcl_AddErrorInfo 3 8.5 Tcl "Tcl Library Procedures" +.so man.macros .BS .SH NAME -Tcl_GetReturnOptions, Tcl_SetReturnOptions, Tcl_AddErrorInfo, Tcl_AddObjErrorInfo, Tcl_SetObjErrorCode, Tcl_SetErrorCode, Tcl_SetErrorCodeVA, Tcl_PosixError, Tcl_LogCommandInfo \- retrieve or record information about errors and other return options +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 .SH SYNOPSIS .nf \fB#include <tcl.h>\fR -.VS 8.5 .sp Tcl_Obj * \fBTcl_GetReturnOptions\fR(\fIinterp, code\fR) .sp -int +int \fBTcl_SetReturnOptions\fR(\fIinterp, options\fR) -.VE 8.5 .sp \fBTcl_AddErrorInfo\fR(\fIinterp, message\fR) .sp +\fBTcl_AppendObjToErrorInfo\fR(\fIinterp, objPtr\fR) +.sp \fBTcl_AddObjErrorInfo\fR(\fIinterp, message, length\fR) .sp \fBTcl_SetObjErrorCode\fR(\fIinterp, errorObjPtr\fR) @@ -34,6 +32,10 @@ int .sp \fBTcl_SetErrorCodeVA\fR(\fIinterp, argList\fR) .sp +\fBTcl_GetErrorLine\fR(\fIinterp\fR) +.sp +\fBTcl_SetErrorLine\fR(\fIinterp, lineNum\fR) +.sp const char * \fBTcl_PosixError\fR(\fIinterp\fR) .sp @@ -43,30 +45,35 @@ void .AS Tcl_Interp commandLength .AP Tcl_Interp *interp in Interpreter in which to record information. -.AP int code +.AP int code The code returned from script evaluation. .AP Tcl_Obj *options A dictionary of return options. .AP char *message in For \fBTcl_AddErrorInfo\fR, -this is a conventional C string to append to the \fB-errorinfo\fR return option. +this is a conventional C string to append to the \fB\-errorinfo\fR return option. For \fBTcl_AddObjErrorInfo\fR, this points to the first byte of an array of \fIlength\fR bytes -containing a string to append to the \fB-errorinfo\fR return option. +containing a string to append to the \fB\-errorinfo\fR return option. This byte array may contain embedded null bytes unless \fIlength\fR is negative. +.AP Tcl_Obj *objPtr in +A message to be appended to the \fB\-errorinfo\fR return option +in the form of a Tcl_Obj value. .AP int length in The number of bytes to copy from \fImessage\fR when -appending to the \fB-errorinfo\fR return option. +appending to the \fB\-errorinfo\fR return option. If negative, all bytes up to the first null byte are used. .AP Tcl_Obj *errorObjPtr in -The \fB-errorcode\fR return option will be set to this value. +The \fB\-errorcode\fR return option will be set to this value. .AP char *element in -String to record as one element of the \fB-errorcode\fR return option. +String to record as one element of the \fB\-errorcode\fR return option. Last \fIelement\fR argument must be NULL. .AP va_list argList in An argument list which must have been initialized using \fBva_start\fR, and cleared using \fBva_end\fR. +.AP int lineNum +The line number of a script where an error occurred. .AP "const char" *script in Pointer to first character in script containing command (must be <= command) .AP "const char" *command in @@ -74,10 +81,8 @@ Pointer to first character in command that generated the error .AP int commandLength in Number of bytes in command; -1 means use all bytes up to first null byte .BE - .SH DESCRIPTION .PP -.VS 8.5 The \fBTcl_SetReturnOptions\fR and \fBTcl_GetReturnOptions\fR routines expose the same capabilities as the \fBreturn\fR and \fBcatch\fR commands, respectively, in the form of a C interface. @@ -94,29 +99,36 @@ of return options. The integer completion code should be passed as the \fIcode\fR argument to \fBTcl_GetReturnOptions\fR so that all required options will be present in the dictionary. Specifically, a \fIcode\fR value of \fBTCL_ERROR\fR will -ensure that entries for the keys \fB-errorinfo\fR, -\fB-errorcode\fR, and \fB-errorline\fR will appear in the -dictionary. Also, the entries for the keys \fB-code\fR -and \fB-level\fR will be adjusted if necessary to agree +ensure that entries for the keys \fB\-errorinfo\fR, +\fB\-errorcode\fR, and \fB\-errorline\fR will appear in the +dictionary. Also, the entries for the keys \fB\-code\fR +and \fB\-level\fR will be adjusted if necessary to agree with the value of \fIcode\fR. The \fB(Tcl_Obj *)\fR returned by \fBTcl_GetReturnOptions\fR points to an unshared \fBTcl_Obj\fR with reference count of zero. The dictionary may be written to, either adding, removing, or overwriting -any entries in it, with the need to check for a shared object. +any entries in it, without the need to check for a shared value. +As with any \fBTcl_Obj\fR with reference count of zero, it is up to +the caller to arrange for its disposal with \fBTcl_DecrRefCount\fR or +to a reference to it via \fBTcl_IncrRefCount\fR (or one of the many +functions that call that, notably including \fBTcl_SetObjResult\fR and +\fBTcl_SetVar2Ex\fR). .PP A typical usage for \fBTcl_GetReturnOptions\fR is to retrieve the stack trace when script evaluation returns \fBTCL_ERROR\fR, like so: +.PP .CS -int code = Tcl_Eval(interp, script); +int code = Tcl_EvalEx(interp, script, -1, 0); if (code == TCL_ERROR) { - Tcl_Obj *options = Tcl_GetReturnOptions(interp, code); + Tcl_Obj *options = \fBTcl_GetReturnOptions\fR(interp, code); Tcl_Obj *key = Tcl_NewStringObj("-errorinfo", -1); Tcl_Obj *stackTrace; Tcl_IncrRefCount(key); Tcl_DictObjGet(NULL, options, key, &stackTrace); Tcl_DecrRefCount(key); /* Do something with stackTrace */ + Tcl_DecrRefCount(options); } .CE .PP @@ -125,20 +137,22 @@ of \fIinterp\fR to be \fIoptions\fR. If \fIoptions\fR contains any invalid value for any key, TCL_ERROR will be returned, and the interp result will be set to an appropriate error message. Otherwise, a completion code -in agreement with the \fB-code\fR and \fB-level\fR +in agreement with the \fB\-code\fR and \fB\-level\fR keys in \fIoptions\fR will be returned. .PP As an example, Tcl's \fBreturn\fR command itself could be implemented in terms of \fBTcl_SetReturnOptions\fR like so: +.PP .CS if ((objc % 2) == 0) { /* explicit result argument */ objc--; Tcl_SetObjResult(interp, objv[objc]); } -return Tcl_SetReturnOptions(interp, Tcl_NewListObj(objc-1, objv+1)); +return \fBTcl_SetReturnOptions\fR(interp, Tcl_NewListObj(objc-1, objv+1)); .CE -(It's not really implemented that way. Internal access +.PP +(It is not really implemented that way. Internal access privileges allow for a more efficient alternative that meshes better with the bytecode compiler.) .PP @@ -149,44 +163,47 @@ to any reference counting. This is analogous to .PP While \fBTcl_SetReturnOptions\fR provides a general interface to set any collection of return options, there are a handful -of return options that are very frequently used. Most -notably the \fB-errorinfo\fR and \fB-errorcode\fR return +of return options that are very frequently used. Most +notably the \fB\-errorinfo\fR and \fB\-errorcode\fR return options should be set properly when the command procedure -of a command returns \fBTCL_ERROR\fR. Tcl provides several -simpler interfaces to more directly set these return options. -.VE 8.5 +of a command returns \fBTCL_ERROR\fR. The \fB\-errorline\fR +return option is also read by commands that evaluate scripts +and wish to supply detailed error location information in +the stack trace text they append to the \fB\-errorinfo\fR option. +Tcl provides several simpler interfaces to more directly set +these return options. .PP -The \fB-errorinfo\fR option holds a stack trace of the +The \fB\-errorinfo\fR option holds a stack trace of the operations that were in progress when an error occurred, and is intended to be human-readable. -The \fB-errorcode\fR option holds a list of items that +The \fB\-errorcode\fR option holds a Tcl list of items that are intended to be machine-readable. -The first item in the \fB-errocode\fR value identifies the class of +The first item in the \fB\-errorcode\fR value identifies the class of error that occurred -(e.g. POSIX means an error occurred in a POSIX system call) +(e.g., POSIX means an error occurred in a POSIX system call) and additional elements hold additional pieces of information that depend on the class. -See the tclvars manual entry for details on the various -formats for the \fB-errorcode\fR option used by -Tcl's built-in commands. +See the manual entry on the \fBerrorCode\fR variable for details on the +various formats for the \fB\-errorcode\fR option used by Tcl's built-in +commands. .PP -The \fB-errorinfo\fR option value is gradually built up as an +The \fB\-errorinfo\fR option value is gradually built up as an error unwinds through the nested operations. Each time an error code is returned to \fBTcl_Eval\fR, or any of the routines that performs script evaluation, the procedure \fBTcl_AddErrorInfo\fR is called to add -additional text to the \fB-errorinfo\fR value describing the +additional text to the \fB\-errorinfo\fR value describing the command that was being executed when the error occurred. By the time the error has been passed all the way back to the application, it will contain a complete trace of the activity in progress when the error occurred. .PP It is sometimes useful to add additional information to -the \fB-errorinfo\fR value beyond what can be supplied automatically +the \fB\-errorinfo\fR value beyond what can be supplied automatically by the script evaluation routines. \fBTcl_AddErrorInfo\fR may be used for this purpose: its \fImessage\fR argument is an additional -string to be appended to the \fB-errorinfo\fR option. +string to be appended to the \fB\-errorinfo\fR option. For example, when an error arises during the \fBsource\fR command, the procedure \fBTcl_AddErrorInfo\fR is called to record the name of the file being processed and the @@ -196,13 +213,18 @@ Tcl procedures, the procedure name and line number within the procedure are recorded, and so on. The best time to call \fBTcl_AddErrorInfo\fR is just after a script evaluation routine has returned \fBTCL_ERROR\fR. -The value of the \fB-errorline\fR return option (retrieved +The value of the \fB\-errorline\fR return option (retrieved via a call to \fBTcl_GetReturnOptions\fR) often makes up a useful part of the \fImessage\fR passed to \fBTcl_AddErrorInfo\fR. .PP +\fBTcl_AppendObjToErrorInfo\fR is an alternative interface to the +same functionality as \fBTcl_AddErrorInfo\fR. \fBTcl_AppendObjToErrorInfo\fR +is called when the string value to be appended to the \fB\-errorinfo\fR option +is available as a \fBTcl_Obj\fR instead of as a \fBchar\fR array. +.PP \fBTcl_AddObjErrorInfo\fR is nearly identical to \fBTcl_AddErrorInfo\fR, except that it has an additional \fIlength\fR -argument. This allows the \fImessage\fR string to contain +argument. This allows the \fImessage\fR string to contain embedded null bytes. This is essentially never a good idea. If the \fImessage\fR needs to contain the null character \fBU+0000\fR, Tcl's usual internal encoding rules should be used to avoid @@ -210,26 +232,31 @@ the need for a null byte. If the \fBTcl_AddObjErrorInfo\fR interface is used at all, it should be with a negative \fIlength\fR value. .PP The procedure \fBTcl_SetObjErrorCode\fR is used to set the -\fB-errorcode\fR return option to the list object \fIerrorObjPtr\fR -built up by the caller. -\fBTcl_SetObjErrorCode\fR is typically invoked just +\fB\-errorcode\fR return option to the list value \fIerrorObjPtr\fR +built up by the caller. +\fBTcl_SetObjErrorCode\fR is typically invoked just before returning an error. If an error is returned without calling \fBTcl_SetObjErrorCode\fR or \fBTcl_SetErrorCode\fR the Tcl interpreter automatically sets -the \fB-errorcode\fR return option to \fBNONE\fR. +the \fB\-errorcode\fR return option to \fBNONE\fR. .PP The procedure \fBTcl_SetErrorCode\fR is also used to set the -\fB-errorcode\fR return option. However, it takes one or more strings to -record instead of an object. Otherwise, it is similar to +\fB\-errorcode\fR return option. However, it takes one or more strings to +record instead of a value. Otherwise, it is similar to \fBTcl_SetObjErrorCode\fR in behavior. .PP \fBTcl_SetErrorCodeVA\fR is the same as \fBTcl_SetErrorCode\fR except that instead of taking a variable number of arguments it takes an argument list. .PP +The procedure \fBTcl_GetErrorLine\fR is used to read the integer value +of the \fB\-errorline\fR return option without the overhead of a full +call to \fBTcl_GetReturnOptions\fR. Likewise, \fBTcl_SetErrorLine\fR +sets the \fB\-errorline\fR return option value. +.PP \fBTcl_PosixError\fR -sets the \fB-errorcode\fR variable after an error in a POSIX kernel call. +sets the \fB\-errorcode\fR variable after an error in a POSIX kernel call. It reads the value of the \fBerrno\fR C variable and calls -\fBTcl_SetErrorCode\fR to set the \fB-errorcode\fR return +\fBTcl_SetErrorCode\fR to set the \fB\-errorcode\fR return option in the \fBPOSIX\fR format. The caller must previously have called \fBTcl_SetErrno\fR to set \fBerrno\fR; this is necessary on some platforms (e.g. Windows) where Tcl @@ -240,15 +267,15 @@ occurs in a dynamically loaded extension. See the manual entry for \fBTcl_PosixError\fR returns a human-readable diagnostic message for the error (this is the same value that will appear as the third element -in the \fB-errorcode\fR value). +in the \fB\-errorcode\fR value). It may be convenient to include this string as part of the error message returned to the application in the interpreter's result. .PP \fBTcl_LogCommandInfo\fR is invoked after an error occurs in an interpreter. It adds information about the command that was being -executed when the error occurred to the \fB-errorinfo\fR value, and -the line number stored internally in the interpreter is set. +executed when the error occurred to the \fB\-errorinfo\fR value, and +the line number stored internally in the interpreter is set. .PP In older releases of Tcl, there was no \fBTcl_GetReturnOptions\fR routine. In its place, the global Tcl variables \fBerrorInfo\fR @@ -261,7 +288,7 @@ global variables remains a supported way to access these return option values, it is important not to assume that writing to those global variables will properly set the corresponding return options. It has long been emphasized -in this manual page that it is important to +in this manual page that it is important to call the procedures described here rather than setting \fBerrorInfo\fR or \fBerrorCode\fR directly with \fBTcl_ObjSetVar2\fR. @@ -269,8 +296,8 @@ setting \fBerrorInfo\fR or \fBerrorCode\fR directly with If the procedure \fBTcl_ResetResult\fR is called, it clears all of the state of the interpreter associated with script evaluation, including the entire return options dictionary. -In particular, the \fB-errorinfo\fR and \fB-errorcode\fR options -are reset. +In particular, the \fB\-errorinfo\fR and \fB\-errorcode\fR options +are reset. If an error had occurred, the \fBTcl_ResetResult\fR call will clear the error state to make it appear as if no error had occurred after all. @@ -278,9 +305,8 @@ The global variables \fBerrorInfo\fR and \fBerrorCode\fR are not modified by \fBTcl_ResetResult\fR so they continue to hold a record of information about the most recent error seen in an interpreter. - .SH "SEE ALSO" -Tcl_DecrRefCount, Tcl_IncrRefCount, Tcl_Interp, Tcl_ResetResult, Tcl_SetErrno - +Tcl_DecrRefCount(3), Tcl_IncrRefCount(3), Tcl_Interp(3), Tcl_ResetResult(3), +Tcl_SetErrno(3), errorCode(n), errorInfo(n) .SH KEYWORDS -error, object, object result, stack, trace, variable +error, value, value result, stack, trace, variable |