diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/AddErrInfo.3 | 253 | ||||
| -rw-r--r-- | doc/Async.3 | 13 | ||||
| -rw-r--r-- | doc/BackgdErr.3 | 32 | ||||
| -rw-r--r-- | doc/SaveResult.3 | 8 | ||||
| -rw-r--r-- | doc/after.n | 12 | ||||
| -rw-r--r-- | doc/bgerror.n | 24 | ||||
| -rw-r--r-- | doc/error.n | 50 | ||||
| -rw-r--r-- | doc/exec.n | 15 | ||||
| -rw-r--r-- | doc/exit.n | 8 | ||||
| -rw-r--r-- | doc/fileevent.n | 6 | ||||
| -rw-r--r-- | doc/interp.n | 17 | ||||
| -rw-r--r-- | doc/return.n | 12 | ||||
| -rw-r--r-- | doc/tclvars.n | 55 | ||||
| -rw-r--r-- | doc/update.n | 4 |
14 files changed, 303 insertions, 206 deletions
diff --git a/doc/AddErrInfo.3 b/doc/AddErrInfo.3 index b7a388c..1185e3c 100644 --- a/doc/AddErrInfo.3 +++ b/doc/AddErrInfo.3 @@ -5,21 +5,29 @@ '\" 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.11 2004/10/07 15:15:35 dkf Exp $ +'\" RCS: @(#) $Id: AddErrInfo.3,v 1.12 2004/11/20 00:17:31 dgp Exp $ '\" .so man.macros .TH Tcl_AddErrorInfo 3 8.0 Tcl "Tcl Library Procedures" .BS .SH NAME -Tcl_AddObjErrorInfo, Tcl_AddErrorInfo, Tcl_SetObjErrorCode, Tcl_SetErrorCode, Tcl_SetErrorCodeVA, Tcl_PosixError, Tcl_LogCommandInfo \- record information about errors +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 .SH SYNOPSIS .nf \fB#include <tcl.h>\fR +.VS 8.5 .sp -\fBTcl_AddObjErrorInfo\fR(\fIinterp, message, length\fR) +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_AddObjErrorInfo\fR(\fIinterp, message, length\fR) +.sp \fBTcl_SetObjErrorCode\fR(\fIinterp, errorObjPtr\fR) .sp \fBTcl_SetErrorCode\fR(\fIinterp, element, element, ... \fB(char *) NULL\fR) @@ -35,22 +43,26 @@ void .AS Tcl_Interp commandLength .AP Tcl_Interp *interp in Interpreter in which to record information. +.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. For \fBTcl_AddObjErrorInfo\fR, -this points to the first byte of an array of bytes -containing a string to record in the \fBerrorInfo\fR variable. +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. -For \fBTcl_AddErrorInfo\fR, -this is a conventional C string to record in the \fBerrorInfo\fR variable. .AP int length in The number of bytes to copy from \fImessage\fR when -setting the \fBerrorInfo\fR variable. +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 -This variable \fBerrorCode\fR 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 \fBerrorCode\fR variable. +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 @@ -65,70 +77,149 @@ Number of bytes in command; -1 means use all bytes up to first null byte .SH DESCRIPTION .PP -These procedures are used to manipulate two Tcl global variables -that hold information about errors. -The variable \fBerrorInfo\fR holds a stack trace of the +.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. +.PP +\fBTcl_GetObjResult\fR retrieves the dictionary of return options +from an interpreter following a script evaluation. +Routines such as \fBTcl_Eval\fR are called to evaluate a +script in an interpreter. These routines return an integer +completion code. These routines also leave in the interpreter +both a result and a dictionary of return options generated +by script evaluation. Just as \fBTcl_GetObjResult\fR retrieves +the result, \fBTcl_GetReturnOptions\fR retrieves the dictionary +of return options. The integer completion code should be +passed as the \fIcode\fR argument to \fBTcl_GetObjResult\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 +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. +.PP +A typical usage for \fBTcl_GetReturnOptions\fR is to +retrieve the stack trace when script evaluation returns +\fBTCL_ERROR\fR, like so: +.CS +int code = Tcl_Eval(interp, script); +if (code == TCL_ERROR) { + Tcl_Obj *options = Tcl_GetReturnOptions(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 */ +} +.CE +.PP +\fBTcl_SetReturnOptions\fR sets the return options +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 +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: +.CS +if ((objc % 2) == 0) { /* explicit result argument */ + objc--; + Tcl_SetObjResult(interp, objv[objc]); +} +return Tcl_SetReturnOptions(interp, Tcl_NewListObj(objc-1, objv+1)); +.CE +(It's not really implemented that way. Internal access +privileges allow for a more efficient alternative that meshes +better with the bytecode compiler.) +.PP +Note that a newly created \fBTcl_Obj\fR may be passed +in as the \fIoptions\fR argument without the need to tend +to any reference counting. This is analogous to +\fBTcl_SetObjResult\fR. +.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 +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 +.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 variable \fBerrorCode\fR holds a list of items that +The \fB-errorcode\fR option holds a list of items that are intended to be machine-readable. -The first item in \fBerrorCode\fR identifies the class of +The first item in the \fB-errocode\fR value identifies the class of error that occurred (e.g. POSIX means an error occurred in a POSIX system call) -and additional elements in \fBerrorCode\fR hold additional pieces +and additional elements hold additional pieces of information that depend on the class. -See the Tcl overview manual entry for details on the various -formats for \fBerrorCode\fR. +See the tclvars manual entry for details on the various +formats for the \fB-errorcode\fR option used by +Tcl's built-in commands. .PP -The \fBerrorInfo\fR variable 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_EvalObjEx\fR -(or \fBTcl_Eval\fR, which calls \fBTcl_EvalObjEx\fR) -it calls the procedure \fBTcl_AddObjErrorInfo\fR to add -additional text to \fBerrorInfo\fR describing the +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 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 -\fBerrorInfo\fR beyond what can be supplied automatically -by \fBTcl_EvalObjEx\fR. -\fBTcl_AddObjErrorInfo\fR may be used for this purpose: -its \fImessage\fR and \fIlength\fR arguments describe an additional -string to be appended to \fBerrorInfo\fR. -For example, the \fBsource\fR command calls \fBTcl_AddObjErrorInfo\fR -to record the name of the file being processed and the -line number on which the error occurred; -for Tcl procedures, the procedure name and line number +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. +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 +line number on which the error occurred. +Likewise, when an error arises during evaluation of a +Tcl procedures, the procedure name and line number within the procedure are recorded, and so on. -The best time to call \fBTcl_AddObjErrorInfo\fR is just after -\fBTcl_EvalObjEx\fR has returned \fBTCL_ERROR\fR. -In calling \fBTcl_AddObjErrorInfo\fR, you may find it useful to -use the \fBerrorLine\fR field of the interpreter (see the -\fBTcl_Interp\fR manual entry for details). -.PP -\fBTcl_AddErrorInfo\fR resembles \fBTcl_AddObjErrorInfo\fR -but differs in initializing \fBerrorInfo\fR from the string -value of the interpreter's result -if the error is just starting to be logged. -It does not use the result as a Tcl object -so any embedded null characters in the result -will cause information to be lost. -It also takes a conventional C string in \fImessage\fR -instead of \fBTcl_AddObjErrorInfo\fR's counted string. +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 +via a call to \fBTcl_GetReturnOptions\fR) often makes up +a useful part of the \fImessage\fT passed to \fBTcl_AddErrorInfo\fR. +.PP +\fBTcl_AddObjErrorInfo\fR is nearly identical +to \fBTcl_AddObjErrorInfo\fR, except that it has an additional \fIlength\fR +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 +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 -\fBerrorCode\fR variable. \fIerrorObjPtr\fR contains a list object -built up by the caller. \fBerrorCode\fR is set to this -value. \fBTcl_SetObjErrorCode\fR is typically invoked just -before returning an error in an object command. If an error is +\fB-errorcode\fR return option to the list object \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 -\fBerrorCode\fR to \fBNONE\fR. +the \fB-errorcode\fR return option to \fBNONE\fR. .PP The procedure \fBTcl_SetErrorCode\fR is also used to set the -\fBerrorCode\fR variable. However, it takes one or more strings to +\fB-errorcode\fR return option. However, it takes one or more strings to record instead of an object. Otherwise, it is similar to \fBTcl_SetObjErrorCode\fR in behavior. .PP @@ -136,9 +227,10 @@ record instead of an object. Otherwise, it is similar to instead of taking a variable number of arguments it takes an argument list. .PP \fBTcl_PosixError\fR -sets the \fBerrorCode\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 \fBerrorCode\fR in the \fBPOSIX\fR format. +\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 is linked into an application as a shared library, or when the error @@ -148,41 +240,44 @@ 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 \fBerrorCode\fR). +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 \fBerrorInfo\fR variable, and -the line number stored internally in the interpreter is set. On the -first call to \fBTcl_LogCommandInfo\fR or \fBTcl_AddObjErrorInfo\fR -since an error occurred, the old information in \fBerrorInfo\fR is -deleted. +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 +and \fBerrorCode\fR were the only place to retrieve the error +information. Much existing code written for older Tcl releases +still access this information via those global variables. .PP -It is important to call the procedures described here rather than +It is important to realize that while reading from those +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 +call the procedures described here rather than setting \fBerrorInfo\fR or \fBerrorCode\fR directly with \fBTcl_ObjSetVar2\fR. -The reason for this is that the Tcl interpreter keeps information -about whether these procedures have been called. -For example, the first time \fBTcl_AddObjErrorInfo\fR is called -for an error, it clears the existing value of \fBerrorInfo\fR -and adds the error message in the interpreter's result to the variable -before appending \fImessage\fR; -in subsequent calls, it just appends the new \fImessage\fR. -When \fBTcl_SetErrorCode\fR is called, it sets a flag indicating -that \fBerrorCode\fR has been set; -this allows the Tcl interpreter to set \fBerrorCode\fR to \fBNONE\fR -if it receives an error return -when \fBTcl_SetErrorCode\fR hasn't been called. .PP If the procedure \fBTcl_ResetResult\fR is called, -it clears all of the state associated with -\fBerrorInfo\fR and \fBerrorCode\fR -(but it doesn't actually modify the variables). -If an error had occurred, this will clear the error state to -make it appear as if no error had occurred after all. +it clears all of the state of ther interpreter associated with +script evaluation, including the entire return options dictionary. +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. +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 +more recent error seen in an interpreter. .SH "SEE ALSO" Tcl_DecrRefCount, Tcl_IncrRefCount, Tcl_Interp, Tcl_ResetResult, Tcl_SetErrno diff --git a/doc/Async.3 b/doc/Async.3 index 3c40c44..cae4318 100644 --- a/doc/Async.3 +++ b/doc/Async.3 @@ -5,7 +5,7 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: Async.3,v 1.6 2004/10/07 14:44:31 dkf Exp $ +'\" RCS: @(#) $Id: Async.3,v 1.7 2004/11/20 00:17:31 dgp Exp $ '\" .so man.macros .TH Tcl_AsyncCreate 3 7.0 Tcl "Tcl Library Procedures" @@ -152,12 +152,11 @@ This sort of behavior can disrupt the execution of scripts in subtle ways and result in bugs that are extremely difficult to track down. If an asynchronous event handler needs to evaluate Tcl scripts -then it should first save the interpreter's result plus the values -of the variables \fBerrorInfo\fR and \fBerrorCode\fR (this can -be done, for example, by storing them in dynamic strings). +then it should first save the interpreter's state by calling +\fBTcl_SaveInterpState\fR, passing in the \fIcode\fR argument. When the asynchronous handler is finished it should restore -the interpreter's result, \fBerrorInfo\fR, and \fBerrorCode\fR, -and return the \fIcode\fR argument. +the interpreter's state by calling \fBTcl_RestoreInterpState\fR, +and then returning the \fIcode\fR argument. .SH KEYWORDS -asynchronous event, handler, signal +asynchronous event, handler, signal, Tcl_SaveInterpState diff --git a/doc/BackgdErr.3 b/doc/BackgdErr.3 index 1ac84c4..315e3b9 100644 --- a/doc/BackgdErr.3 +++ b/doc/BackgdErr.3 @@ -5,7 +5,7 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: BackgdErr.3,v 1.3 2000/04/14 23:01:48 hobbs Exp $ +'\" RCS: @(#) $Id: BackgdErr.3,v 1.4 2004/11/20 00:17:31 dgp Exp $ '\" .so man.macros .TH Tcl_BackgroundError 3 7.5 Tcl "Tcl Library Procedures" @@ -34,25 +34,29 @@ In these cases the code calls \fBTcl_BackgroundError\fR with an \fIinterp\fR argument identifying the interpreter in which the error occurred. At the time \fBTcl_BackgroundError\fR is invoked, the interpreter's result is expected to contain an error message. -\fBTcl_BackgroundError\fR will invoke the \fBbgerror\fR -Tcl command to report the error in an application-specific fashion. -If no \fBbgerror\fR command exists, or if it returns with an error condition, -then \fBTcl_BackgroundError\fR reports the error itself by printing -a message on the standard error file. +\fBTcl_BackgroundError\fR will invoke the command registered +in that interpreter to handle background errors by the +\fBinterp bgerror\fR command. +The registered handler command is meant to report the error +in an application-specific fashion. The handler command +receives two arguments, the result of the interp, and the +return options of the interp at the time the error occurred. +If the application registers no handler command, the default +handler command will attempt to call \fBbgerror\fR to report +the error. If an error condition arises while invoking the +handler command, then \fBTcl_BackgroundError\fR reports the +error itself by printing a message on the standard error file. .PP -\fBTcl_BackgroundError\fR does not invoke \fBbgerror\fR immediately +\fBTcl_BackgroundError\fR does not invoke the handler command immediately because this could potentially interfere with scripts that are in process at the time the error occurred. -Instead, it invokes \fBbgerror\fR later as an idle callback. -\fBTcl_BackgroundError\fR saves the values of the \fBerrorInfo\fR and -\fBerrorCode\fR variables and restores these values just before -invoking \fBbgerror\fR. +Instead, it invokes the handler command later as an idle callback. .PP It is possible for many background errors to accumulate before -\fBbgerror\fR is invoked. When this happens, each of the errors -is processed in order. However, if \fBbgerror\fR returns a +the handler command is invoked. When this happens, each of the errors +is processed in order. However, if the handle command returns a break exception, then all remaining error reports for the interpreter are skipped. .SH KEYWORDS -background, bgerror, error +background, bgerror, error, interp diff --git a/doc/SaveResult.3 b/doc/SaveResult.3 index b2bb744..e250f70 100644 --- a/doc/SaveResult.3 +++ b/doc/SaveResult.3 @@ -5,7 +5,7 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: SaveResult.3,v 1.3 2004/11/18 22:04:39 dgp Exp $ +'\" RCS: @(#) $Id: SaveResult.3,v 1.4 2004/11/20 00:17:31 dgp Exp $ '\" .so man.macros .TH Tcl_SaveResult 3 8.1 Tcl "Tcl Library Procedures" @@ -62,8 +62,8 @@ These routines are passed a pointer to a \fBTcl_SavedResult\fR structure that is used to store enough information to restore the interpreter result. This structure can be allocated on the stack of the calling procedure. These routines do not save the state of any error -information in the interpreter (e.g. the \fBerrorCode\fR or -\fBerrorInfo\fR variables). +information in the interpreter (e.g. the \fB-errorcode\fR or +\fB-errorinfo\fR return options, when an error is in progress). .PP Because the routines \fBTcl_SaveInterpState\fR, \fBTcl_RestoreInterpState\fB, and \fBTcl_DiscardInterpState\fR perform @@ -77,7 +77,7 @@ of existing programs that may already be using them. interpreter state that make up the full result of script evaluation. This include the interpreter result, the return code (passed in as the \fIstatus\fR argument, and any return options, including -the errorInfo and errorCode information when an error is in progress. +\fB-errorinfo\fR and \fB-errorcode\fR when an error is in progress. This snapshot is returned as an opaque token of type \fBTcl_InterpState\fR. The call to \fBTcl_SaveInterpState\fR does not itself change the state of the interpreter. Unlike \fBTcl_SaveResult\fR, it does diff --git a/doc/after.n b/doc/after.n index 5cabb98..bd778dc 100644 --- a/doc/after.n +++ b/doc/after.n @@ -5,7 +5,7 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: after.n,v 1.6 2004/10/27 14:24:37 dkf Exp $ +'\" RCS: @(#) $Id: after.n,v 1.7 2004/11/20 00:17:31 dgp Exp $ '\" .so man.macros .TH after n 7.5 Tcl "Tcl Built-In Commands" @@ -48,8 +48,9 @@ The delayed command is formed by concatenating all the \fIscript\fR arguments in the same fashion as the \fBconcat\fR command. The command will be executed at global level (outside the context of any Tcl procedure). -If an error occurs while executing the delayed command then the -\fBbgerror\fR mechanism is used to report the error. +If an error occurs while executing the delayed command then +the background error will be reported by the command +registered with \fB interp bgerror\fR. The \fBafter\fR command returns an identifier that can be used to cancel the delayed command using \fBafter cancel\fR. .TP @@ -78,7 +79,8 @@ loop is entered and there are no events to process. The command returns an identifier that can be used to cancel the delayed command using \fBafter cancel\fR. If an error occurs while executing the script then the -\fBbgerror\fR mechanism is used to report the error. +background error will be reported by the command +registered with \fB interp bgerror\fR. .TP \fBafter info \fR?\fIid\fR? This command returns information about existing event handlers. @@ -136,7 +138,7 @@ doOneStep .CE .SH "SEE ALSO" -bgerror(n), concat(n), update(n), vwait(n) +concat(n), interp(n), update(n), vwait(n) .SH KEYWORDS cancel, delay, idle callback, sleep, time diff --git a/doc/bgerror.n b/doc/bgerror.n index c20e8a0..88922c0 100644 --- a/doc/bgerror.n +++ b/doc/bgerror.n @@ -5,7 +5,7 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: bgerror.n,v 1.8 2004/11/13 00:19:05 dgp Exp $ +'\" RCS: @(#) $Id: bgerror.n,v 1.9 2004/11/20 00:17:31 dgp Exp $ '\" .so man.macros .TH bgerror n 7.5 Tcl "Tcl Built-In Commands" @@ -49,8 +49,10 @@ unwinding ends in the Tcl library and there is no obvious way for Tcl to report the error. .PP When Tcl detects a background error, it saves information about the -error and invokes the \fBbgerror\fR command later as an idle event -handler. Before invoking \fBbgerror\fR, Tcl restores the +error and invokes a handler command registered by \fBinterp bgerror\fR +later as an idle event handler. The default handler command in turn +calls the \fBbgerror\fR command . +Before invoking \fBbgerror\fR, Tcl restores the \fBerrorInfo\fR and \fBerrorCode\fR variables to their values at the time the error occurred, then it invokes \fBbgerror\fR with the error message as its only argument. Tcl assumes that the application has @@ -69,22 +71,6 @@ error, in the order they occurred. However, if \fBbgerror\fR returns with a break exception, then any remaining errors are skipped without calling \fBbgerror\fR. .PP -Tcl has no default implementation for \fBbgerror\fR. However, in -applications using Tk there is a default \fBbgerror\fR procedure which -posts a dialog box containing the error message and offers the user a -chance to see a stack trace showing where the error occurred. In -addition to allowing the user to view the stack trace, the dialog -provides an additional application configurable button which may be -used, for example, to save the stack trace to a file. By default, -this is the behavior associated with that button. This behavior can -be redefined by setting the option database values -\fB*ErrorDialog.function.text\fR, to specify the caption for the -function button, and \fB*ErrorDialog.function.command\fR, to specify -the command to be run. The text of the stack trace is appended to the -command when it is evaluated. If either of these options is set to -the empty string, then the additional button will not be displayed in -the dialog. -.PP If you are writing code that will be used by others as part of a package or other kind of library, consider avoiding \fBbgerror\fR. The reason for this is that the application programmer may also want diff --git a/doc/error.n b/doc/error.n index 35bad4d..72cbf52 100644 --- a/doc/error.n +++ b/doc/error.n @@ -5,7 +5,7 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: error.n,v 1.6 2004/10/27 09:36:58 dkf Exp $ +'\" RCS: @(#) $Id: error.n,v 1.7 2004/11/20 00:17:31 dgp Exp $ '\" .so man.macros .TH error n "" Tcl "Tcl Built-In Commands" @@ -23,36 +23,42 @@ Returns a \fBTCL_ERROR\fR code, which causes command interpretation to be unwound. \fIMessage\fR is a string that is returned to the application to indicate what went wrong. .PP -If the \fIinfo\fR argument is provided and is non-empty, -it is used to initialize the global variable \fBerrorInfo\fR. -\fBerrorInfo\fR is used to accumulate a stack trace of what -was in progress when an error occurred; as nested commands unwind, -the Tcl interpreter adds information to \fBerrorInfo\fR. If the -\fIinfo\fR argument is present, it is used to initialize -\fBerrorInfo\fR and the first increment of unwind information -will not be added by the Tcl interpreter. In other +The \fB-errorinfo\fB return option of an interpreter is used +to accumulate a stack trace of what was in progress when an +error occurred; as nested commands unwind, +the Tcl interpreter adds information to the \fB-errorinfo\fR +return option. If the \fIinfo\fR argument is present, it is +used to initialize the \fB-errorinfo\fR return options and +the first increment of unwind information +will not be added by the Tcl interpreter. +In other words, the command containing the \fBerror\fR command will not appear -in \fBerrorInfo\fR; in its place will be \fIinfo\fR. -This feature is most useful in conjunction with the \fBcatch\fR command: +in the stack trace; in its place will be \fIinfo\fR. +Historically, this feature had been most useful in conjunction +with the \fBcatch\fR command: if a caught error cannot be handled successfully, \fIinfo\fR can be used to return a stack trace reflecting the original point of occurrence of the error: .CS \fBcatch {...} errMsg -set savedInfo $errorInfo +set savedInfo $::errorInfo \&... error $errMsg $savedInfo\fR .CE +When working with Tcl 8.5 or later, the following code +should be used instead: +.CS +\fBcatch {...} errMsg options +\&... +return -options $options $errMsg\fR +.CE .PP If the \fIcode\fR argument is present, then its value is stored -in the \fBerrorCode\fR global variable. This variable is intended -to hold a machine-readable description of the error in cases where -such information is available; see the \fBtclvars\fR manual -page for information on the proper format for the variable. -If the \fIcode\fR argument is not -present, then \fBerrorCode\fR is automatically reset to -``NONE'' by the Tcl interpreter as part of processing the -error generated by the command. +in the \fB-errorcode\fR return option. The \fB-errorcode\fR +return option is intended to hold a machine-readable description +of the error in cases where such information is available; see +the \fBreturn\fR manual page for information on the proper format +for this option's value. .SH EXAMPLE Generate an error if a basic mathematical operation fails: .CS @@ -62,7 +68,7 @@ if {1+2 != 3} { .CE .SH "SEE ALSO" -catch(n), return(n), tclvars(n) +catch(n), return(n) .SH KEYWORDS -error, errorCode, errorInfo +error @@ -5,7 +5,7 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: exec.n,v 1.12 2004/10/27 09:36:58 dkf Exp $ +'\" RCS: @(#) $Id: exec.n,v 1.13 2004/11/20 00:17:32 dgp Exp $ '\" .so man.macros .TH exec n 8.5 Tcl "Tcl Built-In Commands" @@ -134,7 +134,7 @@ If any of the commands in the pipeline exit abnormally or are killed or suspended, then \fBexec\fR will return an error and the error message will include the pipeline's output followed by error messages describing the abnormal terminations; the -\fBerrorCode\fR variable will contain additional information +\fB-errorcode\fR return option will contain additional information about the last abnormal termination encountered. If any of the commands writes to its standard error file and that standard error isn't redirected, @@ -337,13 +337,14 @@ To execute a simple program and get its result: .CE .PP To execute a program that can return a non-zero result, you should -wrap the call to \fBexec\fR in \fBcatch\fR and check what the contents -of the global \fBerrorCode\fR variable is if you have an error: +wrap the call to \fBexec\fR in \fBcatch\fR and check the contents +of the \fB-errorcode\fR return option if you have an error: .CS set status 0 -if {[catch {\fBexec\fR grep foo bar.txt} results]} { - if {[lindex $::errorCode 0] eq "CHILDSTATUS"} { - set status [lindex $::errorCode 2] +if {[catch {\fBexec\fR grep foo bar.txt} results options]} { + set details [dict get $options -errorcode] + if {[lindex $details 0] eq "CHILDSTATUS"} { + set status [lindex $details 2] } else { # Some kind of unexpected failure } @@ -5,7 +5,7 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: exit.n,v 1.5 2004/10/27 09:36:58 dkf Exp $ +'\" RCS: @(#) $Id: exit.n,v 1.6 2004/11/20 00:17:32 dgp Exp $ '\" .so man.macros .TH exit n "" Tcl "Tcl Built-In Commands" @@ -33,11 +33,11 @@ proc main {} { # ... put the real main code in here ... } -if {[catch {main} msg]} { +if {[catch {main} msg options]} { puts stderr "unexpected script error: $msg" if {[info exist env(DEBUG)]} { puts stderr "---- BEGIN TRACE ----" - puts stderr $errorInfo + puts stderr [dict get $options -errorinfo] puts stderr "---- END TRACE ----" } @@ -47,7 +47,7 @@ if {[catch {main} msg]} { .CE .SH "SEE ALSO" -exec(n), tclvars(n) +exec(n) .SH KEYWORDS exit, process diff --git a/doc/fileevent.n b/doc/fileevent.n index f5ac7fc..a5e4acf 100644 --- a/doc/fileevent.n +++ b/doc/fileevent.n @@ -5,7 +5,7 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: fileevent.n,v 1.6 2004/10/27 12:53:22 dkf Exp $ +'\" RCS: @(#) $Id: fileevent.n,v 1.7 2004/11/20 00:17:32 dgp Exp $ '\" .so man.macros .TH fileevent n 7.5 Tcl "Tcl Built-In Commands" @@ -96,7 +96,7 @@ The script for a file event is executed at global level (outside the context of any Tcl procedure) in the interpreter in which the \fBfileevent\fR command was invoked. If an error occurs while executing the script then the -\fBbgerror\fR mechanism is used to report the error. +command registered with \fBinterp bgerror\fR is used to report the error. In addition, the file event handler is deleted if it ever returns an error; this is done in order to prevent infinite loops due to buggy handlers. @@ -119,7 +119,7 @@ proc GetData {chan} { by Mark Diekhans. .SH "SEE ALSO" -bgerror(n), fconfigure(n), gets(n), puts(n), read(n), Tcl_StandardChannels(3) +fconfigure(n), gets(n), interp(n), puts(n), read(n), Tcl_StandardChannels(3) .SH KEYWORDS asynchronous I/O, blocking, channel, event handler, nonblocking, readable, diff --git a/doc/interp.n b/doc/interp.n index 6517a71..b3e79e1 100644 --- a/doc/interp.n +++ b/doc/interp.n @@ -5,7 +5,7 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: interp.n,v 1.20 2004/11/12 23:27:59 dkf Exp $ +'\" RCS: @(#) $Id: interp.n,v 1.21 2004/11/20 00:17:32 dgp Exp $ '\" .so man.macros .TH interp n 7.6 Tcl "Tcl Built-In Commands" @@ -178,9 +178,9 @@ exists, the command raises an error. This command concatenates all of the \fIarg\fR arguments in the same fashion as the \fBconcat\fR command, then evaluates the resulting string as a Tcl script in the slave interpreter identified by \fIpath\fR. The result -of this evaluation (including error information such as the \fBerrorInfo\fR -and \fBerrorCode\fR variables, if an error occurs) is returned to the -invoking interpreter. +of this evaluation (including all \fBreturn\fT options, +such as \fB-errorinfo\fR and \fB-errorcode\fR information, if an error occurs) +is returned to the invoking interpreter. Note that the script will be executed in the current context stack frame of the \fIpath\fR interpreter; this is so that the implementations (in a master interpreter) of aliases in a slave interpreter can execute scripts in @@ -362,9 +362,9 @@ what to set the interpreter's background error to. See the This command concatenates all of the \fIarg\fR arguments in the same fashion as the \fBconcat\fR command, then evaluates the resulting string as a Tcl script in \fIslave\fR. -The result of this evaluation (including error information -such as the \fBerrorInfo\fR and \fBerrorCode\fR variables, if an -error occurs) is returned to the invoking interpreter. +The result of this evaluation (including all \fBreturn\fT options, +such as \fB-errorinfo\fR and \fB-errorcode\fR information, if an error occurs) +is returned to the invoking interpreter. Note that the script will be executed in the current context stack frame of \fIslave\fR; this is so that the implementations (in a master interpreter) of aliases in a slave interpreter can execute scripts in @@ -688,7 +688,8 @@ reading and writing the option when the particular limit in the limited interpreter is exceeded. The callback may modify the limit on the interpreter if it wishes the limited interpreter to continue executing. If the callback generates an error, it is reported through -the background error mechansism (see \fBbgerror\fR). Note that the +the background error mechansism (see \fBBACKGROUND ERROR HANDLING\fR). +Note that the callbacks defined by one interpreter are completely isolated from the callbacks defined by another, and that the order in which those callbacks are called is undefined. diff --git a/doc/return.n b/doc/return.n index e08dc05..1f884e9 100644 --- a/doc/return.n +++ b/doc/return.n @@ -6,7 +6,7 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: return.n,v 1.11 2004/10/27 14:24:37 dkf Exp $ +'\" RCS: @(#) $Id: return.n,v 1.12 2004/11/20 00:17:32 dgp Exp $ '\" .so man.macros .TH return n 8.5 Tcl "Tcl Built-In Commands" @@ -106,14 +106,14 @@ recognized and treated specially by Tcl. They are: .TP \fB-errorcode \fIlist\fR The \fB-errorcode\fR option receives special treatment only when the value -of the \fB-code\fR option is \fBTCL_ERROR\fR. Then the \fIlist\fR value, which -must be a valid Tcl list, is stored in the global variable \fBerrorCode\fR. -The \fIlist\fR value is meant to be additional information about the error, +of the \fB-code\fR option is \fBTCL_ERROR\fR. Then the \fIlist\fR value +is meant to be additional information about the error, presented as a Tcl list for further processing by programs. If no \fB-errorcode\fR option is provided to \fBreturn\fR when the \fB-code error\fR option is provided, Tcl will set the value -of both the \fB-errorcode\fR entry in the return options dictionary and -the global variable \fBerrorCode\fR to the default value of \fBNONE\fR. +of the \fB-errorcode\fR entry in the return options dictionary +to the default value of \fBNONE\fR. The \fB-errorcode\fR return +option will also be stored in the global variable \fBerrorCode\fR. .TP \fB-errorinfo \fIinfo\fR The \fB-errorinfo\fR option receives special treatment only when the value diff --git a/doc/tclvars.n b/doc/tclvars.n index 6a25087..f1d0055 100644 --- a/doc/tclvars.n +++ b/doc/tclvars.n @@ -5,7 +5,7 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: tclvars.n,v 1.19 2004/11/15 21:46:05 dkf Exp $ +'\" RCS: @(#) $Id: tclvars.n,v 1.20 2004/11/20 00:17:32 dgp Exp $ '\" .so man.macros .TH tclvars n 8.0 Tcl "Tcl Built-In Commands" @@ -51,14 +51,15 @@ won't work on windows and is discouraged for cross-platform usage. .RE .TP \fBerrorCode\fR -After an error has occurred, this variable will be set to hold -additional information about the error in a form that is easy -to process with programs. -\fBerrorCode\fR consists of a Tcl list with one or more elements. +This variable holds the value of the \fB-errorcode\fR return option +set by the most recent error that occurred in this interpreter. +This list value represents additional information about the error +in a form that is easy to process with programs. The first element of the list identifies a general class of errors, and determines the format of the rest of the list. -The following formats for \fBerrorCode\fR are used by the -Tcl core; individual applications may define additional formats. +The following formats for \fB-errorcode\fR return options +are used by the Tcl core; individual applications may define +additional formats. .RS .TP \fBARITH\fI code msg\fR @@ -74,59 +75,61 @@ or UNKNOWN (if the cause of the error cannot be determined). .TP \fBCHILDKILLED\fI pid sigName msg\fR This format is used when a child process has been killed because of -a signal. The second element of \fBerrorCode\fR will be the -process's identifier (in decimal). -The third element will be the symbolic name of the signal that caused +a signal. The \fIpid\fR element will be the process's identifier (in decimal). +The \fIsigName\fR element will be the symbolic name of the signal that caused the process to terminate; it will be one of the names from the include file signal.h, such as \fBSIGPIPE\fR. -The fourth element will be a short human-readable message +The \fImsg\fR element will be a short human-readable message describing the signal, such as ``write on pipe with no readers'' for \fBSIGPIPE\fR. .TP \fBCHILDSTATUS\fI pid code\fR This format is used when a child process has exited with a non-zero -exit status. The second element of \fBerrorCode\fR will be the -process's identifier (in decimal) and the third element will be the exit +exit status. The \fIpid\fR element will be the +process's identifier (in decimal) and the \fIcode\fR element will be the exit code returned by the process (also in decimal). .TP \fBCHILDSUSP\fI pid sigName msg\fR This format is used when a child process has been suspended because of a signal. -The second element of \fBerrorCode\fR will be the process's identifier, -in decimal. -The third element will be the symbolic name of the signal that caused +The \fIpid\fR element will be the process's identifier, in decimal. +The \fIsigName\fR element will be the symbolic name of the signal that caused the process to suspend; this will be one of the names from the include file signal.h, such as \fBSIGTTIN\fR. -The fourth element will be a short human-readable message +The \fImsg\fR element will be a short human-readable message describing the signal, such as ``background tty read'' for \fBSIGTTIN\fR. .TP \fBNONE\fR This format is used for errors where no additional information is available for an error besides the message returned with the -error. In these cases \fBerrorCode\fR will consist of a list -containing a single element whose contents are \fBNONE\fR. +error. In these cases the \fB-errorcode\fR return option +will consist of a list containing a single element whose +contents are \fBNONE\fR. .TP \fBPOSIX \fIerrName msg\fR -If the first element of \fBerrorCode\fR is \fBPOSIX\fR, then +If the first element is \fBPOSIX\fR, then the error occurred during a POSIX kernel call. -The second element of the list will contain the symbolic name +The \fIerrName\fR element will contain the symbolic name of the error that occurred, such as \fBENOENT\fR; this will be one of the values defined in the include file errno.h. -The third element of the list will be a human-readable +The \fImsg\fR element will be a human-readable message corresponding to \fIerrName\fR, such as ``no such file or directory'' for the \fBENOENT\fR case. .PP -To set \fBerrorCode\fR, applications should use library -procedures such as \fBTcl_SetErrorCode\fR and \fBTcl_PosixError\fR, -or they may invoke the \fBerror\fR command. +To set the \fB-errorcode\fR return option, applications should use library +procedures such as \fBTcl_SetObjErrorCode\fR, \fBTcl_SetReturnOptions\fR, +and \fBTcl_PosixError\fR, or they may invoke the \fB-errorcode\fR +option of the \fBreturn\fR command. If one of these methods hasn't been used, then the Tcl interpreter will reset the variable to \fBNONE\fR after the next error. .RE .TP \fBerrorInfo\fR -After an error has occurred, this string will contain one or more lines +This variable holds the value of the \fB-errorinfo\fR return option +set by the most recent error that occurred in this interpreter. +This string value will contain one or more lines identifying the Tcl commands and procedures that were being executed when the most recent error occurred. Its contents take the form of a stack trace showing the various diff --git a/doc/update.n b/doc/update.n index 060ffb7..ebe89d4 100644 --- a/doc/update.n +++ b/doc/update.n @@ -5,7 +5,7 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: update.n,v 1.5 2004/05/28 12:56:23 dkf Exp $ +'\" RCS: @(#) $Id: update.n,v 1.6 2004/11/20 00:17:32 dgp Exp $ '\" .so man.macros .TH update n 7.5 Tcl "Tcl Built-In Commands" @@ -61,7 +61,7 @@ while {!$done} { .CE .SH "SEE ALSO" -after(n), bgerror(n) +after(n), interp(n) .SH KEYWORDS event, flush, handler, idle, update |