1 | '\" |
---|
2 | '\" Copyright (c) 1993-1994 The Regents of the University of California. |
---|
3 | '\" Copyright (c) 1994-1996 Sun Microsystems, Inc. |
---|
4 | '\" Contributions from Don Porter, NIST, 2003. (not subject to US copyright) |
---|
5 | '\" |
---|
6 | '\" See the file "license.terms" for information on usage and redistribution |
---|
7 | '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. |
---|
8 | '\" |
---|
9 | '\" RCS: @(#) $Id: catch.n,v 1.18 2007/12/13 15:22:32 dgp Exp $ |
---|
10 | '\" |
---|
11 | .so man.macros |
---|
12 | .TH catch n "8.5" Tcl "Tcl Built-In Commands" |
---|
13 | .BS |
---|
14 | '\" Note: do not modify the .SH NAME line immediately below! |
---|
15 | .SH NAME |
---|
16 | catch \- Evaluate script and trap exceptional returns |
---|
17 | .SH SYNOPSIS |
---|
18 | \fBcatch\fI script \fR?\fIresultVarName\fR? ?\fIoptionsVarName\fR? |
---|
19 | .BE |
---|
20 | |
---|
21 | .SH DESCRIPTION |
---|
22 | .PP |
---|
23 | The \fBcatch\fR command may be used to prevent errors from aborting command |
---|
24 | interpretation. The \fBcatch\fR command calls the Tcl interpreter recursively to |
---|
25 | execute \fIscript\fR, and always returns without raising an error, |
---|
26 | regardless of any errors that might occur while executing \fIscript\fR. |
---|
27 | .PP |
---|
28 | If \fIscript\fR raises an error, \fBcatch\fR will return a non-zero integer |
---|
29 | value corresponding to the exceptional return code returned by evaluation |
---|
30 | of \fIscript\fR. Tcl defines the normal return code from script |
---|
31 | evaluation to be zero (0), or \fBTCL_OK\fR. Tcl also defines four exceptional |
---|
32 | return codes: 1 (\fBTCL_ERROR\fR), 2 (\fBTCL_RETURN\fR), 3 (\fBTCL_BREAK\fR), |
---|
33 | and 4 (\fBTCL_CONTINUE\fR). Errors during evaluation of a script are indicated |
---|
34 | by a return code of \fBTCL_ERROR\fR. The other exceptional return codes are |
---|
35 | returned by the \fBreturn\fR, \fBbreak\fR, and \fBcontinue\fR commands |
---|
36 | and in other special situations as documented. Tcl packages can define |
---|
37 | new commands that return other integer values as return codes as well, |
---|
38 | and scripts that make use of the \fBreturn -code\fR command can also |
---|
39 | have return codes other than the five defined by Tcl. |
---|
40 | .PP |
---|
41 | If the \fIresultVarName\fR argument is given, then the variable it names is |
---|
42 | set to the result of the script evaluation. When the return code from |
---|
43 | the script is 1 (\fBTCL_ERROR\fR), the value stored in \fIresultVarName\fR is an error |
---|
44 | message. When the return code from the script is 0 (\fBTCL_OK\fR), the value |
---|
45 | stored in \fIresultVarName\fR is the value returned from \fIscript\fR. |
---|
46 | .PP |
---|
47 | .VS 8.5 |
---|
48 | If the \fIoptionsVarName\fR argument is given, then the variable it |
---|
49 | names is set to a dictionary of return options returned by evaluation |
---|
50 | of \fIscript\fR. Tcl specifies two entries that are always |
---|
51 | defined in the dictionary: \fB\-code\fR and \fB\-level\fR. When |
---|
52 | the return code from evaluation of \fIscript\fR is not \fBTCL_RETURN\fR, |
---|
53 | the value of the \fB\-level\fR entry will be 0, and the value |
---|
54 | of the \fB\-code\fR entry will be the same as the return code. |
---|
55 | Only when the return code is \fBTCL_RETURN\fR will the values of |
---|
56 | the \fB\-level\fR and \fB\-code\fR entries be something else, as |
---|
57 | further described in the documentation for the \fBreturn\fR command. |
---|
58 | .PP |
---|
59 | When the return code from evaluation of \fIscript\fR is \fBTCL_ERROR\fR, |
---|
60 | three additional entries are defined in the dictionary of return options |
---|
61 | stored in \fIoptionsVarName\fR: \fB\-errorinfo\fR, \fB\-errorcode\fR, |
---|
62 | and \fB\-errorline\fR. The value of the \fB\-errorinfo\fR entry |
---|
63 | is a formatted stack trace containing more information about |
---|
64 | the context in which the error happened. The formatted stack |
---|
65 | trace is meant to be read by a person. The value of |
---|
66 | the \fB\-errorcode\fR entry is additional information about the |
---|
67 | error stored as a list. The \fB\-errorcode\fR value is meant to |
---|
68 | be further processed by programs, and may not be particularly |
---|
69 | readable by people. The value of the \fB\-errorline\fR entry |
---|
70 | is an integer indicating which line of \fIscript\fR was being |
---|
71 | evaluated when the error occurred. The values of the \fB\-errorinfo\fR |
---|
72 | and \fB\-errorcode\fR entries of the most recent error are also |
---|
73 | available as values of the global variables \fB::errorInfo\fR |
---|
74 | and \fB::errorCode\fR respectively. |
---|
75 | .PP |
---|
76 | Tcl packages may provide commands that set other entries in the |
---|
77 | dictionary of return options, and the \fBreturn\fR command may be |
---|
78 | used by scripts to set return options in addition to those defined |
---|
79 | above. |
---|
80 | .VE 8.5 |
---|
81 | .SH EXAMPLES |
---|
82 | The \fBcatch\fR command may be used in an \fBif\fR to branch based on |
---|
83 | the success of a script. |
---|
84 | .CS |
---|
85 | if { [\fBcatch\fR {open $someFile w} fid] } { |
---|
86 | puts stderr "Could not open $someFile for writing\en$fid" |
---|
87 | exit 1 |
---|
88 | } |
---|
89 | .CE |
---|
90 | .PP |
---|
91 | There are more complex examples of \fBcatch\fR usage in the |
---|
92 | documentation for the \fBreturn\fR command. |
---|
93 | |
---|
94 | .SH "SEE ALSO" |
---|
95 | break(n), continue(n), dict(n), error(n), return(n), tclvars(n) |
---|
96 | |
---|
97 | .SH KEYWORDS |
---|
98 | catch, error |
---|