summaryrefslogtreecommitdiffstats
path: root/doc
diff options
context:
space:
mode:
authorferrieux <ferrieux@users.sourceforge.net>2009-11-16 17:38:08 (GMT)
committerferrieux <ferrieux@users.sourceforge.net>2009-11-16 17:38:08 (GMT)
commit3ffda83a5b3d9b03fa4bad1e5384919a46adf47a (patch)
tree1b93d42b56b88ab1862f7389658528282be889d6 /doc
parentd264119bd45f0b0e694574efc0a627ac1a4232cb (diff)
downloadtcl-3ffda83a5b3d9b03fa4bad1e5384919a46adf47a.zip
tcl-3ffda83a5b3d9b03fa4bad1e5384919a46adf47a.tar.gz
tcl-3ffda83a5b3d9b03fa4bad1e5384919a46adf47a.tar.bz2
(forward port) Fix [Bug 2891556] and improve test to detect similar manifestations in the future. Add tcltest support for finalization.
Diffstat (limited to 'doc')
-rw-r--r--doc/catch.n45
-rw-r--r--doc/info.n12
2 files changed, 39 insertions, 18 deletions
diff --git a/doc/catch.n b/doc/catch.n
index bf302ba..f06220b 100644
--- a/doc/catch.n
+++ b/doc/catch.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: catch.n,v 1.20 2008/10/17 10:22:25 dkf Exp $
+'\" RCS: @(#) $Id: catch.n,v 1.21 2009/11/16 17:38:08 ferrieux Exp $
'\"
.so man.macros
.TH catch n "8.5" Tcl "Tcl Built-In Commands"
@@ -54,22 +54,33 @@ Only when the return code is \fBTCL_RETURN\fR will the values of
the \fB\-level\fR and \fB\-code\fR entries be something else, as
further described in the documentation for the \fBreturn\fR command.
.PP
-When the return code from evaluation of \fIscript\fR is \fBTCL_ERROR\fR,
-three additional entries are defined in the dictionary of return options
-stored in \fIoptionsVarName\fR: \fB\-errorinfo\fR, \fB\-errorcode\fR,
-and \fB\-errorline\fR. The value of the \fB\-errorinfo\fR entry
-is a formatted stack trace containing more information about
-the context in which the error happened. The formatted stack
-trace is meant to be read by a person. The value of
-the \fB\-errorcode\fR entry is additional information about the
-error stored as a list. The \fB\-errorcode\fR value is meant to
-be further processed by programs, and may not be particularly
-readable by people. The value of the \fB\-errorline\fR entry
-is an integer indicating which line of \fIscript\fR was being
-evaluated when the error occurred. The values of the \fB\-errorinfo\fR
-and \fB\-errorcode\fR entries of the most recent error are also
-available as values of the global variables \fB::errorInfo\fR
-and \fB::errorCode\fR respectively.
+When the return code from evaluation of \fIscript\fR is
+\fBTCL_ERROR\fR, four additional entries are defined in the dictionary
+of return options stored in \fIoptionsVarName\fR: \fB\-errorinfo\fR,
+\fB\-errorcode\fR, \fB\-errorline\fR, and \fB\-errorstack\fR. The
+value of the \fB\-errorinfo\fR entry is a formatted stack trace
+containing more information about the context in which the error
+happened. The formatted stack trace is meant to be read by a person.
+The value of the \fB\-errorcode\fR entry is additional information
+about the error stored as a list. The \fB\-errorcode\fR value is
+meant to be further processed by programs, and may not be particularly
+readable by people. The value of the \fB\-errorline\fR entry is an
+integer indicating which line of \fIscript\fR was being evaluated when
+the error occurred. The value of the \fB\-errorstack\fR entry is a
+list of lists made of the function names and arguments at each level
+from the call stack when the error occurred. It differs from
+-errorinfo in that (1) it is a true list of lists, for easy
+programmatic access without parsing, (2) it contains the true
+(substituted) values passed to the functions, instead of the static
+text of the calling sites, and (3) it is coarser-grained, with only
+one element per stack frame (like procs; no separate elements for
+[foreach] constructs for example).
+
+The values of the \fB\-errorinfo\fR and \fB\-errorcode\fR entries of
+the most recent error are also available as values of the global
+variables \fB::errorInfo\fR and \fB::errorCode\fR respectively. The
+value of the \fB\-errorstack\fR entry surfaces as \fBinfo
+errorstack\fR.
.PP
Tcl packages may provide commands that set other entries in the
dictionary of return options, and the \fBreturn\fR command may be
diff --git a/doc/info.n b/doc/info.n
index b4c4b60..9fd0fde 100644
--- a/doc/info.n
+++ b/doc/info.n
@@ -8,7 +8,7 @@
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\"
-'\" RCS: @(#) $Id: info.n,v 1.33 2009/05/15 10:08:02 dkf Exp $
+'\" RCS: @(#) $Id: info.n,v 1.34 2009/11/16 17:38:08 ferrieux Exp $
'\"
.so man.macros
.TH info n 8.4 Tcl "Tcl Built-In Commands"
@@ -94,6 +94,16 @@ does not have a default value then the command returns \fB0\fR.
Otherwise it returns \fB1\fR and places the default value of \fIarg\fR
into variable \fIvarname\fR.
.TP
+\fBinfo errorstack \fR?\fIinterp\fR?
+.
+Returns a list of lists made of the function names and arguments at
+each level from the call stack of the last error in the given
+\fIinterp\fR, or in the current one if not specified. This
+information is also present in the -errorstack entry of the options
+dictionary returned by 3-arg \fBcatch\fR; \fBinfo errorstack\fR is a
+convenient way of retrieving it for uncaught errors at toplevel in an
+interactive tclsh.
+.TP
\fBinfo exists \fIvarName\fR
.
Returns \fB1\fR if the variable named \fIvarName\fR exists in the