Author:         David Gravereaux <[email protected]>
State:          Draft
Type:           Project
Vote:           Pending
Created:        06-Jul-2026
Tcl-Version:    9.2
Tcl-Branch:     tip-758
Forum:          0c3b3fcb
Keywords:       Tcl, channel drivers

---

Abstract

A Tcl channel represent a data pathway. Not all pathways are the same. For as much as we try to implement the common denominator, some aspects are left out because there is no place for them to go. This TIP proposes a third event name "exception" for the fileevent command associated with the TCL_EXCEPTION mask constant. It shall represent the entryway for all extra things not reading/writing that require an interrupt style of behavior and will be highly specific to the channel driver that uses it.

Specification

A new file event type "exception" is called in case of the reception of specific extra features:

chan event $chan exception command
fileevent $chan exception command

Rationale

I found this limitation while trying to create a channel driver for GPIB as an extension. There is no place for the interrupt handler to go for processing STB on the opened device. It needs a third event handler so that Tcl_NotifyChannel(...,TCL_EXCEPTION) can do something.

This TIP adds the missing functionality at the script level so the driver's Tcl_DriverWatchProc can be called with a mask containing TCL_EXCEPTION while Tcl_NotifyChannel(...,TCL_EXCEPTION) can run the exception script handler provided by fileevent

This could also be a place for adding extra features to the core drivers.

An example would be the serial driver for getting direct notifications of pin changes for RI and DCD rather than having to poll with fconfigure -ttystatus. An implementation for this is outside the scope of this TIP.

Although historically this name comes from select with its exceptfds set, this TIP is only about the usage of TCL_EXCEPTION as it applies to the channel interface, not about any direct mappings the core might be assuming with the Unix implementation. It's interesting to note that to receive notifications of an OOB byte on a TCP socket, select's exceptfds or epoll with POLLPRI is used for that. Reception of OOB on a socket is also a possible feature that could be added. It could look like this:

fileevent $sock exception [list sock_oob $sock [subst -noc {[fconfigure $sock -oob_byte]}]]

proc sock_oob {sock oob} {
    set byte [binary format c $oob]
}

fconfigure $sock -send_oob $byte

An implementation for the above is outside the scope of this TIP.

Note that while having the new "exception" event, channels that aren't created with a validmask that includes TCL_EXCEPTION, will properly fail to set an exception handler script nor call the driver's Tcl_DriverWatchProc with an updated interest:

% fileevent stdout exception foobarbaz
channel is not allowed to have the exception handler

IOW, nothing is changed when you don't use Tcl_CreateChannel(...,TCL_EXCEPTION)

Copyright

This document has been placed in the public domain.