Tcl_StackChannel(3)

💅 NAME 💅

Tcl_StackChannel, Tcl_UnstackChannel, Tcl_GetStackedChannel, Tcl_GetTopChannel — bestie, these four are your stacked I/O channel queens, they literally manipulate them 💖

This one lives in the Tcl Library Procedures section of the manual, section 3, so like… it's a C function page, not a command page. iykyk 🎀

---

✨ SYNOPSIS ✨

#include <tcl.h>

Tcl_Channel
Tcl_StackChannel(interp, typePtr, clientData, mask, channel)

int
Tcl_UnstackChannel(interp, channel)

Tcl_Channel
Tcl_GetStackedChannel(channel)

Tcl_Channel
Tcl_GetTopChannel(channel)

---

🫶 ARGUMENTS 🫶

• Tcl_Interp *interp (in) — the interpreter that gets to do the error reporting, aka the one who tells you what went wrong 😭
• const Tcl_ChannelType *typePtr (in) — the new channel I/O procedures we're gonna use for channel, like a whole new personality for it 🦋
• void *clientData (in) — an arbitrary one-word value that gets passed along to the channel I/O procedures. no cap, it's just a lil something you hand over 🙈
• int mask (in) — the conditions under which channel will be used: an OR-ed combination of TCL_READABLE, TCL_WRITABLE and TCL_EXCEPTION. and get this, it can be a subset of the operations currently allowed on channel. so like, you can take privileges away, not add them ✨
• Tcl_Channel channel (in) — an existing Tcl channel, the kind you'd get back from Tcl_CreateChannel 💜

---

🌸 DESCRIPTION 🌸

Okay so, these functions are for extensions that add processing layers to Tcl I/O channels. Think compression modules. Think encryption modules. Iconic behaviour honestly 👑

They transparently stack and unstack a new channel on top of an existing one. And the way you can just keep going… any number of channels can be stacked together. it's giving tower of channels 🏗️✨

The Tcl_ChannelType version currently supported is TCL_CHANNEL_VERSION_5. Go read Tcl_CreateChannel for the details, bestie 💅

Tcl_StackChannel stacks a new channel on an existing channel, and it uses the same name that was registered for channel by Tcl_RegisterChannel. same name, new layer, main character energy 💖

So how does Tcl_StackChannel actually work? It creates a new channel structure and places itself on top of the channel stack. And here's the tea: EOL translation, encoding and buffering options are shared between all channels in the stack. The hidden channel does no buffering, no newline translations, no character set encoding. Instead, the buffering, newline translations, and encoding functions all stay at the top of the channel stack. A pointer to the new top channel structure gets returned. And if an error happens while stacking the channel, NULL is returned instead 😭 (not the fun kind of plot twist)

The mask parameter specifies the operations that are allowed on the new channel. These can be a subset of the operations allowed on the original channel. For example, a read-write channel may become read-only after the Tcl_StackChannel call. glow down, but make it intentional 🎀

Closing a channel closes the channels stacked below it. The close of stacked channels is executed in a way that allows buffered data to be properly flushed — so no data gets lost in the group chat, we love to see it 🫶

Tcl_UnstackChannel reverses the process. The old channel is associated with the channel name, and the processing module added by Tcl_StackChannel is destroyed. If there is no old channel, then Tcl_UnstackChannel is equivalent to Tcl_Close. If an error occurs unstacking the channel, TCL_ERROR is returned, otherwise TCL_OK is returned. so simple, so clean ✨

Tcl_GetTopChannel returns the top channel in the stack of channels the supplied channel is part of. the queen at the top of the pyramid 👑

Tcl_GetStackedChannel returns the channel in the stack of channels which is just below the supplied channel. the one standing right behind her 💜

---

🔥 SEE ALSO 🔥

Notifier(3), Tcl_CreateChannel(3), Tcl_OpenFileChannel(3), vwait(n)

---

⭐ KEYWORDS ⭐

channel, compression

---

okay bestie that's the whole page, go stack something gorgeous 🦋✨

this was Tcl 8.3, from the Tcl_StackChannel(3) page, and yes the footer says the same thing — bye, ily, go flush your buffers 💅💖