Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
catch(n)		     Tcl Built-In Commands		      catch(n)

______________________________________________________________________________

NAME
       catch - Evaluate	script and trap	exceptional returns

SYNOPSIS
       catch script ?resultVarName? ?optionsVarName?
______________________________________________________________________________

DESCRIPTION
       The  catch  command may be used to prevent errors from aborting command
       interpretation.	The catch command calls	 the  Tcl  interpreter	recur-
       sively  to execute script, and always returns without raising an	error,
       regardless of any errors	that might occur while executing script.

       If script raises	an error, catch	will return a non-zero	integer	 value
       corresponding  to the exceptional return	code returned by evaluation of
       script.	Tcl defines the	normal return code from	script	evaluation  to
       be  zero	 (0),  or  TCL_OK.   Tcl  also defines four exceptional	return
       codes: 1	(TCL_ERROR), 2 (TCL_RETURN), 3 (TCL_BREAK),  and  4  (TCL_CON-
       TINUE).	Errors during evaluation of a script are indicated by a	return
       code of TCL_ERROR.  The other exceptional return	codes are returned  by
       the  return,  break,  and continue commands and in other	special	situa-
       tions 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 return -code command can also have return	codes other  than  the
       five defined by Tcl.

       If  the	resultVarName 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 (TCL_ERROR), the value stored	in resultVarName is an
       error message.  When the	return code from the script is 0 (TCL_OK), the
       value stored in resultVarName is	the value returned from	script.

       If  the optionsVarName argument is given, then the variable it names is |
       set to a	dictionary of return options returned by evaluation of script. |
       Tcl  specifies  two  entries that are always defined in the dictionary: |
       -code and -level.  When the return code from evaluation	of  script  is |
       not  TCL_RETURN,	the value of the -level	entry will be 0, and the value |
       of the -code entry will be the same as the return code.	Only when  the |
       return  code  is	TCL_RETURN will	the values of the -level and -code en- |
       tries be	something else,	as further described in	the documentation  for |
       the return command.						       |

       When  the return	code from evaluation of	script is TCL_ERROR, three ad- |
       ditional	entries	are defined in the dictionary of return	options	stored |
       in  optionsVarName:  -errorinfo,	-errorcode, and	-errorline.  The value |
       of the -errorinfo entry is a formatted stack trace containing more  in- |
       formation about the context in which the	error happened.	 The formatted |
       stack trace is meant to be read by a person.  The value of the  -error- |
       code  entry is additional information about the error stored as a list. |
       The -errorcode value is meant to	be further processed by	programs,  and |
       may  not	 be particularly readable by people.  The value	of the -error- |
       line entry is an	integer	indicating which  line	of  script  was	 being |
       evaluated  when	the  error occurred.  The values of the	-errorinfo and |
       -errorcode entries of the most recent error are also available as  val- |
       ues of the global variables ::errorInfo and ::errorCode respectively.   |

       Tcl packages may	provide	commands that set other	entries	in the dictio- |
       nary of return options, and the return command may be used  by  scripts |
       to set return options in	addition to those defined above.

EXAMPLES
       The  catch  command may be used in an if	to branch based	on the success
       of a script.
	      if { [catch {open	$someFile w} fid] } {
		  puts stderr "Could not open $someFile	for writing\n$fid"
		  exit 1
	      }

       There are more complex examples of catch	usage in the documentation for
       the return command.

SEE ALSO
       break(n), continue(n), dict(n), error(n), return(n), tclvars(n)

KEYWORDS
       catch, error

Tcl				      8.5			      catch(n)

NAME | SYNOPSIS | DESCRIPTION | EXAMPLES | SEE ALSO | KEYWORDS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=catch.tcl85&manpath=FreeBSD+13.0-RELEASE+and+Ports>

home | help