diff options
Diffstat (limited to 'doc/AddErrInfo.3')
| -rw-r--r-- | doc/AddErrInfo.3 | 130 |
1 files changed, 78 insertions, 52 deletions
diff --git a/doc/AddErrInfo.3 b/doc/AddErrInfo.3 index 5332e6a..d4bf7d5 100644 --- a/doc/AddErrInfo.3 +++ b/doc/AddErrInfo.3 @@ -5,27 +5,25 @@ '\" 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.14 2005/08/05 01:58:52 dgp Exp $ -'\" +.TH Tcl_AddErrorInfo 3 8.5 Tcl "Tcl Library Procedures" .so man.macros -.TH Tcl_AddErrorInfo 3 8.0 Tcl "Tcl Library Procedures" .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 \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 @@ -49,24 +51,29 @@ The code returned from script evaluation. 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 -\fBTCL_VARARGS_START\fR, and cleared using \fBva_end\fR. +\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); 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 @@ -150,43 +164,46 @@ to any reference counting. This is analogous to 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 +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,10 +213,15 @@ 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 @@ -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 +\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,14 +267,14 @@ 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 +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 @@ -269,7 +296,7 @@ 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 +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 @@ -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 |