diff options
Diffstat (limited to 'doc/AddErrInfo.3')
| -rw-r--r-- | doc/AddErrInfo.3 | 88 |
1 files changed, 50 insertions, 38 deletions
diff --git a/doc/AddErrInfo.3 b/doc/AddErrInfo.3 index 577b6c7..caba125 100644 --- a/doc/AddErrInfo.3 +++ b/doc/AddErrInfo.3 @@ -4,29 +4,25 @@ '\" '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" +'\" .TH Tcl_AddErrorInfo 3 8.5 Tcl "Tcl Library Procedures" .so man.macros .BS .SH NAME -Tcl_GetReturnOptions, Tcl_SetReturnOptions, Tcl_AddErrorInfo, Tcl_AppendObjToErrorInfo, 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) -.VS 8.5 .sp \fBTcl_AppendObjToErrorInfo\fR(\fIinterp, objPtr\fR) -.VE 8.5 .sp \fBTcl_AddObjErrorInfo\fR(\fIinterp, message, length\fR) .sp @@ -36,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 @@ -45,7 +45,7 @@ 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. @@ -57,11 +57,9 @@ 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. This byte array may contain embedded null bytes unless \fIlength\fR is negative. -.VS 8.5 .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. -.VE 8.5 .AP int length in The number of bytes to copy from \fImessage\fR when appending to the \fB\-errorinfo\fR return option. @@ -74,6 +72,8 @@ 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 @@ -81,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. @@ -109,21 +107,28 @@ 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, without 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 @@ -138,13 +143,15 @@ keys in \fIoptions\fR will be returned. 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 +.PP (It is not really implemented that way. Internal access privileges allow for a more efficient alternative that meshes better with the bytecode compiler.) @@ -156,26 +163,29 @@ 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 +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 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\-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 error unwinds through the nested operations. @@ -207,16 +217,14 @@ 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 -.VS 8.5 \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. -.VE 8.5 .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 @@ -224,9 +232,9 @@ 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 @@ -234,12 +242,17 @@ 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 +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. It reads the value of the \fBerrno\fR C variable and calls @@ -262,7 +275,7 @@ the interpreter's result. \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. +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 @@ -275,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. @@ -284,7 +297,7 @@ 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. +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. @@ -292,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 |