---
name: "tcllib_try"
section: "3tcl"
platform: "linux"
package: "tcllib"
version: "2.0+dfsg-4"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/tcllib_try"
---

# tcllib\_try(3tcl)

try - Trap and process errors and exceptions

```

```

## NAME

try - try - Trap and process errors and exceptions

## SYNOPSIS

package require **Tcl 8.5 9**

package require **try ?1.1?**

**::try** *body* ?*handler...*? ?**finally** *script*?

```

```

## DESCRIPTION

This package provides a forward-compatibility implementation of Tcl 8.6's **try**/**finally** command (TIP 329), for Tcl 8.5. The code was directly pulled from Tcl 8.6 revision ?, when try/finally was implemented as Tcl procedure instead of in C.

- **::try** *body* ?*handler...*? ?**finally** *script*?

  This command executes the script *body* and, depending on what the outcome of that script is (normal exit, error, or some other exceptional result), runs a handler script to deal with the case. Once that has all happened, if the **finally** clause is present, the *script* it includes will be run and the result of the handler (or the *body* if no handler matched) is allowed to continue to propagate. Note that the **finally** clause is processed even if an error occurs and irrespective of which, if any, *handler* is used.

  The *handler* clauses are each expressed as several words, and must have one of the following forms:

  - **on** *code variableList script*

    This clause matches if the evaluation of *body* completed with the exception code *code*. The *code* may be expressed as an integer or one of the following literal words: **ok**, **error**, **return**, **break**, or **continue**. Those literals correspond to the integers 0 through 4 respectively.

  - **trap** *pattern variableList script*

    This clause matches if the evaluation of *body* resulted in an error and the prefix of the **-errorcode** from the interpreter's status dictionary is equal to the *pattern*. The number of prefix words taken from the **-errorcode** is equal to the list-length of *pattern*, and inter-word spaces are normalized in both the **-errorcode** and *pattern* before comparison.

    The *variableList* word in each *handler* is always interpreted as a list of variable names. If the first word of the list is present and non-empty, it names a variable into which the result of the evaluation of *body* (from the main **try**) will be placed; this will contain the human-readable form of any errors. If the second word of the list is present and non-empty, it names a variable into which the options dictionary of the interpreter at the moment of completion of execution of *body* will be placed.

    The *script* word of each *handler* is also always interpreted the same: as a Tcl script to evaluate if the clause is matched. If *script* is a literal **-** and the *handler* is not the last one, the *script* of the following *handler* is invoked instead (just like with the **switch** command).

    Note that *handler* clauses are matched against in order, and that the first matching one is always selected. At most one *handler* clause will selected. As a consequence, an **on error** will mask any subsequent **trap** in the **try**. Also note that **on error** is equivalent to **trap {}**.

    If an exception (i.e. any non-**ok** result) occurs during the evaluation of either the *handler* or the **finally** clause, the original exception's status dictionary will be added to the new exception's status dictionary under the **-during** key.

## EXAMPLES

Ensure that a file is closed no matter what:

```
set f [open /some/file/name a]
try {
    puts \$f "some message"
    # ...
} finally {
    close \$f
}
```

Handle different reasons for a file to not be openable for reading:

```
try {
    set f [open /some/file/name]
} trap {POSIX EISDIR} {} {
    puts "failed to open /some/file/name: it's a directory"
} trap {POSIX ENOENT} {} {
    puts "failed to open /some/file/name: it doesn't exist"
}
```

## BUGS, IDEAS, FEEDBACK

This document, and the package it describes, will undoubtedly contain bugs and other problems. Please report such in the category *try* of the *Tcllib Trackers* \[http://core.tcl.tk/tcllib/reportlist\]. Please also report any ideas for enhancements you may have for either package and/or documentation.

When proposing code changes, please provide *unified diffs*, i.e the output of **diff -u**.

Note further that *attachments* are strongly preferred over inlined patches. Attachments can be made by going to the **Edit** form of the ticket immediately after its creation, and then using the left-most button in the secondary navigation bar.

## SEE ALSO

[catch(3tcl)](/catch/3tcl.md), [error(3tcl)](/error/3tcl.md), [return(3tcl)](/return/3tcl.md), [throw(3tcl)](/throw/3tcl.md)

## KEYWORDS

cleanup, error, exception, final, resource management

## CATEGORY

Utility

## COPYRIGHT

```
Copyright (c) 2008 Donal K. Fellows, BSD licensed
```