diff options
Diffstat (limited to 'doc/error.n')
| -rw-r--r-- | doc/error.n | 50 |
1 files changed, 28 insertions, 22 deletions
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 |