126 lines
5.5 KiB
Plaintext
126 lines
5.5 KiB
Plaintext
'\"
|
|
'\" Copyright (c) 1993-1994 The Regents of the University of California.
|
|
'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
|
|
'\" Contributions from Don Porter, NIST, 2003. (not subject to US copyright)
|
|
'\"
|
|
'\" See the file "license.terms" for information on usage and redistribution
|
|
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
|
|
'\"
|
|
.TH catch n "8.5" Tcl "Tcl Built-In Commands"
|
|
.so man.macros
|
|
.BS
|
|
'\" Note: do not modify the .SH NAME line immediately below!
|
|
.SH NAME
|
|
catch \- Evaluate script and trap exceptional returns
|
|
.SH SYNOPSIS
|
|
\fBcatch\fI script \fR?\fIresultVarName\fR? ?\fIoptionsVarName\fR?
|
|
.BE
|
|
.SH DESCRIPTION
|
|
.PP
|
|
The \fBcatch\fR command may be used to prevent errors from aborting command
|
|
interpretation. The \fBcatch\fR command calls the Tcl interpreter recursively
|
|
to execute \fIscript\fR, and always returns without raising an error,
|
|
regardless of any errors that might occur while executing \fIscript\fR.
|
|
.PP
|
|
If \fIscript\fR raises an error, \fBcatch\fR will return a non-zero integer
|
|
value corresponding to the exceptional return code returned by evaluation
|
|
of \fIscript\fR. Tcl defines the normal return code from script
|
|
evaluation to be zero (0), or \fBTCL_OK\fR. Tcl also defines four exceptional
|
|
return codes: 1 (\fBTCL_ERROR\fR), 2 (\fBTCL_RETURN\fR), 3 (\fBTCL_BREAK\fR),
|
|
and 4 (\fBTCL_CONTINUE\fR). Errors during evaluation of a script are indicated
|
|
by a return code of \fBTCL_ERROR\fR. The other exceptional return codes are
|
|
returned by the \fBreturn\fR, \fBbreak\fR, and \fBcontinue\fR commands
|
|
and in other special situations as documented. Tcl packages can define
|
|
new commands that return other integer values as return codes as well,
|
|
and scripts that make use of the \fBreturn \-code\fR command can also
|
|
have return codes other than the five defined by Tcl.
|
|
.PP
|
|
If the \fIresultVarName\fR argument is given, then the variable it names is
|
|
set to the result of the script evaluation. When the return code from the
|
|
script is 1 (\fBTCL_ERROR\fR), the value stored in \fIresultVarName\fR is an
|
|
error message. When the return code from the script is 0 (\fBTCL_OK\fR), the
|
|
value stored in \fIresultVarName\fR is the value returned from \fIscript\fR.
|
|
.PP
|
|
If the \fIoptionsVarName\fR argument is given, then the variable it
|
|
names is set to a dictionary of return options returned by evaluation
|
|
of \fIscript\fR. Tcl specifies two entries that are always
|
|
defined in the dictionary: \fB\-code\fR and \fB\-level\fR. When
|
|
the return code from evaluation of \fIscript\fR is not \fBTCL_RETURN\fR,
|
|
the value of the \fB\-level\fR entry will be 0, and the value
|
|
of the \fB\-code\fR entry will be the same as the return code.
|
|
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, 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
|
|
.VS 8.6
|
|
\fB\-errorstack\fR.
|
|
.VE 8.6
|
|
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.
|
|
.VS 8.6
|
|
The value of the \fB\-errorstack\fR entry is an
|
|
even-sized list made of token-parameter pairs accumulated while
|
|
unwinding the stack. The token may be
|
|
.QW \fBCALL\fR ,
|
|
in which case the parameter is a list made of the proc name and arguments at
|
|
the corresponding level; or it may be
|
|
.QW \fBUP\fR ,
|
|
in which case the parameter is
|
|
the relative level (as in \fBuplevel\fR) of the previous \fBCALL\fR. The
|
|
salient differences with respect to \fB\-errorinfo\fR are that:
|
|
.IP [1]
|
|
it is a machine-readable form that is amenable to processing with
|
|
[\fBforeach\fR {tok prm} ...],
|
|
.IP [2]
|
|
it contains the true (substituted) values passed to the functions, instead of
|
|
the static text of the calling sites, and
|
|
.IP [3]
|
|
it is coarser-grained, with only one element per stack frame (like procs; no
|
|
separate elements for \fBforeach\fR constructs for example).
|
|
.VE 8.6
|
|
.PP
|
|
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.
|
|
.VS 8.6
|
|
The value of the \fB\-errorstack\fR entry surfaces as \fBinfo errorstack\fR.
|
|
.VE 8.6
|
|
.PP
|
|
Tcl packages may provide commands that set other entries in the
|
|
dictionary of return options, and the \fBreturn\fR command may be
|
|
used by scripts to set return options in addition to those defined
|
|
above.
|
|
.SH EXAMPLES
|
|
.PP
|
|
The \fBcatch\fR command may be used in an \fBif\fR to branch based on
|
|
the success of a script.
|
|
.PP
|
|
.CS
|
|
if { [\fBcatch\fR {open $someFile w} fid] } {
|
|
puts stderr "Could not open $someFile for writing\en$fid"
|
|
exit 1
|
|
}
|
|
.CE
|
|
.PP
|
|
There are more complex examples of \fBcatch\fR usage in the
|
|
documentation for the \fBreturn\fR command.
|
|
.SH "SEE ALSO"
|
|
break(n), continue(n), dict(n), error(n), errorCode(n), errorInfo(n), info(n),
|
|
return(n)
|
|
.SH KEYWORDS
|
|
catch, error, exception
|
|
'\" Local Variables:
|
|
'\" mode: nroff
|
|
'\" fill-column: 78
|
|
'\" End:
|