util/X86LINUX64/man/mann/catch.n

   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 .TH catch n "8.5" Tcl "Tcl Built-In Commands"
  10 .\" The -*- nroff -*- definitions below are for supplemental macros used
  11 .\" in Tcl/Tk manual entries.
  12 .\"
  13 .\" .AP type name in/out ?indent?
  14 .\"     Start paragraph describing an argument to a library procedure.
  15 .\"     type is type of argument (int, etc.), in/out is either "in", "out",
  16 .\"     or "in/out" to describe whether procedure reads or modifies arg,
  17 .\"     and indent is equivalent to second arg of .IP (shouldn't ever be
  18 .\"     needed;  use .AS below instead)
  19 .\"
  20 .\" .AS ?type? ?name?
  21 .\"     Give maximum sizes of arguments for setting tab stops.  Type and
  22 .\"     name are examples of largest possible arguments that will be passed
  23 .\"     to .AP later.  If args are omitted, default tab stops are used.
  24 .\"
  25 .\" .BS
  26 .\"     Start box enclosure.  From here until next .BE, everything will be
  27 .\"     enclosed in one large box.
  28 .\"
  29 .\" .BE
  30 .\"     End of box enclosure.
  31 .\"
  32 .\" .CS
  33 .\"     Begin code excerpt.
  34 .\"
  35 .\" .CE
  36 .\"     End code excerpt.
  37 .\"
  38 .\" .VS ?version? ?br?
  39 .\"     Begin vertical sidebar, for use in marking newly-changed parts
  40 .\"     of man pages.  The first argument is ignored and used for recording
  41 .\"     the version when the .VS was added, so that the sidebars can be
  42 .\"     found and removed when they reach a certain age.  If another argument
  43 .\"     is present, then a line break is forced before starting the sidebar.
  44 .\"
  45 .\" .VE
  46 .\"     End of vertical sidebar.
  47 .\"
  48 .\" .DS
  49 .\"     Begin an indented unfilled display.
  50 .\"
  51 .\" .DE
  52 .\"     End of indented unfilled display.
  53 .\"
  54 .\" .SO ?manpage?
  55 .\"     Start of list of standard options for a Tk widget. The manpage
  56 .\"     argument defines where to look up the standard options; if
  57 .\"     omitted, defaults to "options". The options follow on successive
  58 .\"     lines, in three columns separated by tabs.
  59 .\"
  60 .\" .SE
  61 .\"     End of list of standard options for a Tk widget.
  62 .\"
  63 .\" .OP cmdName dbName dbClass
  64 .\"     Start of description of a specific option.  cmdName gives the
  65 .\"     option's name as specified in the class command, dbName gives
  66 .\"     the option's name in the option database, and dbClass gives
  67 .\"     the option's class in the option database.
  68 .\"
  69 .\" .UL arg1 arg2
  70 .\"     Print arg1 underlined, then print arg2 normally.
  71 .\"
  72 .\" .QW arg1 ?arg2?
  73 .\"     Print arg1 in quotes, then arg2 normally (for trailing punctuation).
  74 .\"
  75 .\" .PQ arg1 ?arg2?
  76 .\"     Print an open parenthesis, arg1 in quotes, then arg2 normally
  77 .\"     (for trailing punctuation) and then a closing parenthesis.
  78 .\"
  79 .\"     # Set up traps and other miscellaneous stuff for Tcl/Tk man pages.
  80 .if t .wh -1.3i ^B
  81 .nr ^l \n(.l
  82 .ad b
  83 .\"     # Start an argument description
  84 .de AP
  85 .ie !"\\$4"" .TP \\$4
  86 .el \{\
  87 .   ie !"\\$2"" .TP \\n()Cu
  88 .   el          .TP 15
  89 .\}
  90 .ta \\n()Au \\n()Bu
  91 .ie !"\\$3"" \{\
  92 \&\\$1 \\fI\\$2\\fP (\\$3)
  93 .\".b
  94 .\}
  95 .el \{\
  96 .br
  97 .ie !"\\$2"" \{\
  98 \&\\$1  \\fI\\$2\\fP
  99 .\}
 100 .el \{\
 101 \&\\fI\\$1\\fP
 102 .\}
 103 .\}
 104 ..
 105 .\"     # define tabbing values for .AP
 106 .de AS
 107 .nr )A 10n
 108 .if !"\\$1"" .nr )A \\w'\\$1'u+3n
 109 .nr )B \\n()Au+15n
 110 .\"
 111 .if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n
 112 .nr )C \\n()Bu+\\w'(in/out)'u+2n
 113 ..
 114 .AS Tcl_Interp Tcl_CreateInterp in/out
 115 .\"     # BS - start boxed text
 116 .\"     # ^y = starting y location
 117 .\"     # ^b = 1
 118 .de BS
 119 .br
 120 .mk ^y
 121 .nr ^b 1u
 122 .if n .nf
 123 .if n .ti 0
 124 .if n \l'\\n(.lu\(ul'
 125 .if n .fi
 126 ..
 127 .\"     # BE - end boxed text (draw box now)
 128 .de BE
 129 .nf
 130 .ti 0
 131 .mk ^t
 132 .ie n \l'\\n(^lu\(ul'
 133 .el \{\
 134 .\"     Draw four-sided box normally, but don't draw top of
 135 .\"     box if the box started on an earlier page.
 136 .ie !\\n(^b-1 \{\
 137 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
 138 .\}
 139 .el \}\
 140 \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
 141 .\}
 142 .\}
 143 .fi
 144 .br
 145 .nr ^b 0
 146 ..
 147 .\"     # VS - start vertical sidebar
 148 .\"     # ^Y = starting y location
 149 .\"     # ^v = 1 (for troff;  for nroff this doesn't matter)
 150 .de VS
 151 .if !"\\$2"" .br
 152 .mk ^Y
 153 .ie n 'mc \s12\(br\s0
 154 .el .nr ^v 1u
 155 ..
 156 .\"     # VE - end of vertical sidebar
 157 .de VE
 158 .ie n 'mc
 159 .el \{\
 160 .ev 2
 161 .nf
 162 .ti 0
 163 .mk ^t
 164 \h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n'
 165 .sp -1
 166 .fi
 167 .ev
 168 .\}
 169 .nr ^v 0
 170 ..
 171 .\"     # Special macro to handle page bottom:  finish off current
 172 .\"     # box/sidebar if in box/sidebar mode, then invoked standard
 173 .\"     # page bottom macro.
 174 .de ^B
 175 .ev 2
 176 'ti 0
 177 'nf
 178 .mk ^t
 179 .if \\n(^b \{\
 180 .\"     Draw three-sided box if this is the box's first page,
 181 .\"     draw two sides but no top otherwise.
 182 .ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
 183 .el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
 184 .\}
 185 .if \\n(^v \{\
 186 .nr ^x \\n(^tu+1v-\\n(^Yu
 187 \kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c
 188 .\}
 189 .bp
 190 'fi
 191 .ev
 192 .if \\n(^b \{\
 193 .mk ^y
 194 .nr ^b 2
 195 .\}
 196 .if \\n(^v \{\
 197 .mk ^Y
 198 .\}
 199 ..
 200 .\"     # DS - begin display
 201 .de DS
 202 .RS
 203 .nf
 204 .sp
 205 ..
 206 .\"     # DE - end display
 207 .de DE
 208 .fi
 209 .RE
 210 .sp
 211 ..
 212 .\"     # SO - start of list of standard options
 213 .de SO
 214 'ie '\\$1'' .ds So \\fBoptions\\fR
 215 'el .ds So \\fB\\$1\\fR
 216 .SH "STANDARD OPTIONS"
 217 .LP
 218 .nf
 219 .ta 5.5c 11c
 220 .ft B
 221 ..
 222 .\"     # SE - end of list of standard options
 223 .de SE
 224 .fi
 225 .ft R
 226 .LP
 227 See the \\*(So manual entry for details on the standard options.
 228 ..
 229 .\"     # OP - start of full description for a single option
 230 .de OP
 231 .LP
 232 .nf
 233 .ta 4c
 234 Command-Line Name:      \\fB\\$1\\fR
 235 Database Name:  \\fB\\$2\\fR
 236 Database Class: \\fB\\$3\\fR
 237 .fi
 238 .IP
 239 ..
 240 .\"     # CS - begin code excerpt
 241 .de CS
 242 .RS
 243 .nf
 244 .ta .25i .5i .75i 1i
 245 ..
 246 .\"     # CE - end code excerpt
 247 .de CE
 248 .fi
 249 .RE
 250 ..
 251 .\"     # UL - underline word
 252 .de UL
 253 \\$1\l'|0\(ul'\\$2
 254 ..
 255 .\"     # QW - apply quotation marks to word
 256 .de QW
 257 .ie '\\*(lq'"' ``\\$1''\\$2
 258 .\"" fix emacs highlighting
 259 .el \\*(lq\\$1\\*(rq\\$2
 260 ..
 261 .\"     # PQ - apply parens and quotation marks to word
 262 .de PQ
 263 .ie '\\*(lq'"' (``\\$1''\\$2)\\$3
 264 .\"" fix emacs highlighting
 265 .el (\\*(lq\\$1\\*(rq\\$2)\\$3
 266 ..
 267 .\"     # QR - quoted range
 268 .de QR
 269 .ie '\\*(lq'"' ``\\$1''\\-``\\$2''\\$3
 270 .\"" fix emacs highlighting
 271 .el \\*(lq\\$1\\*(rq\\-\\*(lq\\$2\\*(rq\\$3
 272 ..
 273 .\"     # MT - "empty" string
 274 .de MT
 275 .QW ""
 276 ..
 277 .BS
 278 '\" Note:  do not modify the .SH NAME line immediately below!
 279 .SH NAME
 280 catch \- Evaluate script and trap exceptional returns
 281 .SH SYNOPSIS
 282 \fBcatch\fI script \fR?\fIresultVarName\fR? ?\fIoptionsVarName\fR?
 283 .BE
 284 .SH DESCRIPTION
 285 .PP
 286 The \fBcatch\fR command may be used to prevent errors from aborting command
 287 interpretation.  The \fBcatch\fR command calls the Tcl interpreter recursively
 288 to execute \fIscript\fR, and always returns without raising an error,
 289 regardless of any errors that might occur while executing \fIscript\fR.
 290 .PP
 291 If \fIscript\fR raises an error, \fBcatch\fR will return a non-zero integer
 292 value corresponding to the exceptional return code returned by evaluation
 293 of \fIscript\fR.  Tcl defines the normal return code from script
 294 evaluation to be zero (0), or \fBTCL_OK\fR.  Tcl also defines four exceptional
 295 return codes: 1 (\fBTCL_ERROR\fR), 2 (\fBTCL_RETURN\fR), 3 (\fBTCL_BREAK\fR),
 296 and 4 (\fBTCL_CONTINUE\fR).  Errors during evaluation of a script are indicated
 297 by a return code of \fBTCL_ERROR\fR.  The other exceptional return codes are
 298 returned by the \fBreturn\fR, \fBbreak\fR, and \fBcontinue\fR commands
 299 and in other special situations as documented.  Tcl packages can define
 300 new commands that return other integer values as return codes as well,
 301 and scripts that make use of the \fBreturn \-code\fR command can also
 302 have return codes other than the five defined by Tcl.
 303 .PP
 304 If the \fIresultVarName\fR argument is given, then the variable it names is
 305 set to the result of the script evaluation.  When the return code from the
 306 script is 1 (\fBTCL_ERROR\fR), the value stored in \fIresultVarName\fR is an
 307 error message.  When the return code from the script is 0 (\fBTCL_OK\fR), the
 308 value stored in \fIresultVarName\fR is the value returned from \fIscript\fR.
 309 .PP
 310 If the \fIoptionsVarName\fR argument is given, then the variable it
 311 names is set to a dictionary of return options returned by evaluation
 312 of \fIscript\fR.  Tcl specifies two entries that are always
 313 defined in the dictionary: \fB\-code\fR and \fB\-level\fR.  When
 314 the return code from evaluation of \fIscript\fR is not \fBTCL_RETURN\fR,
 315 the value of the \fB\-level\fR entry will be 0, and the value
 316 of the \fB\-code\fR entry will be the same as the return code.
 317 Only when the return code is \fBTCL_RETURN\fR will the values of
 318 the \fB\-level\fR and \fB\-code\fR entries be something else, as
 319 further described in the documentation for the \fBreturn\fR command.
 320 .PP
 321 When the return code from evaluation of \fIscript\fR is
 322 \fBTCL_ERROR\fR, four additional entries are defined in the dictionary
 323 of return options stored in \fIoptionsVarName\fR: \fB\-errorinfo\fR,
 324 \fB\-errorcode\fR, \fB\-errorline\fR, and
 325 .VS 8.6
 326 \fB\-errorstack\fR.
 327 .VE 8.6
 328 The value of the \fB\-errorinfo\fR entry is a formatted stack trace containing
 329 more information about the context in which the error happened.  The formatted
 330 stack trace is meant to be read by a person.  The value of the
 331 \fB\-errorcode\fR entry is additional information about the error stored as a
 332 list.  The \fB\-errorcode\fR value is meant to be further processed by
 333 programs, and may not be particularly readable by people.  The value of the
 334 \fB\-errorline\fR entry is an integer indicating which line of \fIscript\fR
 335 was being evaluated when the error occurred.
 336 .VS 8.6
 337 The value of the \fB\-errorstack\fR entry is an
 338 even-sized list made of token-parameter pairs accumulated while
 339 unwinding the stack. The token may be
 340 .QW \fBCALL\fR ,
 341 in which case the parameter is a list made of the proc name and arguments at
 342 the corresponding level; or it may be
 343 .QW \fBUP\fR ,
 344 in which case the parameter is
 345 the relative level (as in \fBuplevel\fR) of the previous \fBCALL\fR. The
 346 salient differences with respect to \fB\-errorinfo\fR are that:
 347 .IP [1]
 348 it is a machine-readable form that is amenable to processing with
 349 [\fBforeach\fR {tok prm} ...],
 350 .IP [2]
 351 it contains the true (substituted) values passed to the functions, instead of
 352 the static text of the calling sites, and
 353 .IP [3]
 354 it is coarser-grained, with only one element per stack frame (like procs; no
 355 separate elements for \fBforeach\fR constructs for example).
 356 .VE 8.6
 357 .PP
 358 The values of the \fB\-errorinfo\fR and \fB\-errorcode\fR entries of
 359 the most recent error are also available as values of the global
 360 variables \fB::errorInfo\fR and \fB::errorCode\fR respectively.
 361 .VS 8.6
 362 The value of the \fB\-errorstack\fR entry surfaces as \fBinfo errorstack\fR.
 363 .VE 8.6
 364 .PP
 365 Tcl packages may provide commands that set other entries in the
 366 dictionary of return options, and the \fBreturn\fR command may be
 367 used by scripts to set return options in addition to those defined
 368 above.
 369 .SH EXAMPLES
 370 .PP
 371 The \fBcatch\fR command may be used in an \fBif\fR to branch based on
 372 the success of a script.
 373 .PP
 374 .CS
 375 if { [\fBcatch\fR {open $someFile w} fid] } {
 376     puts stderr "Could not open $someFile for writing\en$fid"
 377     exit 1
 378 }
 379 .CE
 380 .PP
 381 There are more complex examples of \fBcatch\fR usage in the
 382 documentation for the \fBreturn\fR command.
 383 .SH "SEE ALSO"
 384 break(n), continue(n), dict(n), error(n), errorCode(n), errorInfo(n), info(n),
 385 return(n)
 386 .SH KEYWORDS
 387 catch, error, exception
 388 '\" Local Variables:
 389 '\" mode: nroff
 390 '\" fill-column: 78
 391 '\" End: