Tcl_SetChannelError(3)

🦋 Tcl_SetChannelError — the manual, bestie edition 💖

okay so this is a page from the Tcl Library Procedures, all about Tcl_SetChannelError, Tcl_SetChannelErrorInterp, Tcl_GetChannelError and Tcl_GetChannelErrorInterp. yes those names are a mouthful, we'll get through it together 🫶

---

✨ NAME ✨

Tcl_SetChannelError, Tcl_SetChannelErrorInterp, Tcl_GetChannelError, Tcl_GetChannelErrorInterp — functions to create/intercept Tcl errors by channel drivers. that's the whole vibe: channel drivers get to sneak real error messages around the normal rules. no cap. 💅

---

🌈 SYNOPSIS 🌈

#include <tcl.h>

Tcl_SetChannelError(chan, msg)

Tcl_SetChannelErrorInterp(interp, msg)

Tcl_GetChannelError(chan, msgPtr)

Tcl_GetChannelErrorInterp(interp, msgPtr)

---

🎀 ARGUMENTS 🎀

• Tcl_Channel chan (in) — refers to the Tcl channel whose bypass area is accessed. it's giving "the spot we're poking at" 🍓
• Tcl_Interp* interp (in) — refers to the Tcl interpreter whose bypass area is accessed.
• Tcl_Obj* msg (in) — the error message put into a bypass area. a list of return options and values, followed by a string message. both the message and the option/value information are optional. this must be a well-formed list. periodt, no messy lists allowed 💀
• Tcl_Obj** msgPtr (out) — reference to a place where the message stored in the accessed bypass area can be stored in.

---

💖 DESCRIPTION 💖

okay so here's the situation. the standard definition of a Tcl channel driver does not permit the direct return of arbitrary error messages, except for the setting and retrieval of channel options. all other functions are restricted to POSIX error codes. literally just POSIX codes, that's it. 🙈

the functions described here overcome this limitation. channel drivers are allowed to use Tcl_SetChannelError and Tcl_SetChannelErrorInterp to place arbitrary error messages in bypass areas defined for channels and interpreters. and the generic I/O layer uses Tcl_GetChannelError and Tcl_GetChannelErrorInterp to look for messages in the bypass areas and arrange for their return as errors. the POSIX error codes set by a driver are used now if and only if no messages are present. icon behaviour fr fr 👑

Tcl_SetChannelError stores error information in the bypass area of the specified channel. the number of references to the msg value goes up by one. previously stored information will be discarded, by releasing the reference held by the channel. the channel reference must not be NULL.

Tcl_SetChannelErrorInterp stores error information in the bypass area of the specified interpreter. the number of references to the msg value goes up by one. previously stored information will be discarded, by releasing the reference held by the interpreter. the interpreter reference must not be NULL.

Tcl_GetChannelError places either the error message held in the bypass area of the specified channel into msgPtr, or NULL; and resets the bypass, that is, after an invocation all following invocations will return NULL, until an intervening invocation of Tcl_SetChannelError with a non-NULL message. the msgPtr must not be NULL. the reference count of the message is not touched. the reference previously held by the channel is now held by the caller of the function and it is its responsibility to release that reference when it is done with the value. so like, you picked it up, you put it down bestie 🫶

Tcl_GetChannelErrorInterp places either the error message held in the bypass area of the specified interpreter into msgPtr, or NULL; and resets the bypass, that is, after an invocation all following invocations will return NULL, until an intervening invocation of Tcl_SetChannelErrorInterp with a non-NULL message. the msgPtr must not be NULL. the reference count of the message is not touched. the reference previously held by the interpreter is now held by the caller of the function and it is its responsibility to release that reference when it is done with the value.

which functions of a channel driver are allowed to use which bypass function is listed below, as is which functions of the public channel API may leave a messages in the bypass areas. ✨

• Tcl_DriverInputProc — may use Tcl_SetChannelError, and only this function.
• Tcl_DriverOutputProc — may use Tcl_SetChannelError, and only this function.
• Tcl_DriverWideSeekProc — may use Tcl_SetChannelError, and only this function.
• Tcl_DriverSetOptionProc — has already the ability to pass arbitrary error messages. must not use any of the new functions.
• Tcl_DriverGetOptionProc — has already the ability to pass arbitrary error messages. must not use any of the new functions.
• Tcl_DriverWatchProc — must not use any of the new functions. is internally called and has no ability to return any type of error whatsoever. 💀
• Tcl_DriverBlockModeProc — may use Tcl_SetChannelError, and only this function.
• Tcl_DriverGetHandleProc — must not use any of the new functions. it is only a low-level function, and not used by Tcl commands.
• Tcl_DriverHandlerProc — must not use any of the new functions. is internally called and has no ability to return any type of error whatsoever.

given the information above the following public functions of the Tcl C API are affected by these changes; when these functions are called, the channel may now contain a stored arbitrary error message requiring processing by the caller. 👀

Tcl_Flush          Tcl_GetsObj          Tcl_Gets
Tcl_ReadChars      Tcl_ReadRaw          Tcl_Read
Tcl_Seek           Tcl_StackChannel     Tcl_Tell
Tcl_WriteChars     Tcl_WriteObj         Tcl_WriteRaw
Tcl_Write

all other API functions are unchanged. in particular, the functions below leave all their error information in the interpreter result. they're the well-behaved ones, we stan 🌸

Tcl_Close          Tcl_UnstackChannel   Tcl_UnregisterChannel

---

🧚 REFERENCE COUNT MANAGEMENT 🧚

the msg argument to Tcl_SetChannelError and Tcl_SetChannelErrorInterp, if not NULL, may have any reference count; these functions will copy. they're not gonna yank your refcount out from under you, they just copy and move on 💅

Tcl_GetChannelError and Tcl_GetChannelErrorInterp write a value reference into their msgPtr, but do not manipulate its reference count. the reference count will be at least 1 (unless the reference is NULL). so bestie, the ref is yours now, handle it with care 🫶

---

⭐ SEE ALSO ⭐

Tcl_Close(3), Tcl_OpenFileChannel(3), Tcl_SetErrno(3)

---

🔥 KEYWORDS 🔥

channel driver, error messages, channel type

---

and that's the whole page!! this is from the <strong>Tcl Library Procedures</strong>, version <strong>8.5</strong>, and honestly the way this doc ate and left no crumbs — the date situation is a little mysterious ngl but the manual name and version are right here for you. mwah, go forth and return arbitrary error messages responsibly 💖✨🎀