Tcl_StackChannel(3tcl)

💖 Tcl_StackChannel — the stacked-channel glow-up 💖

okay bestie, pull up a chair because we're about to talk about layers. not like, outfit layers (though slay), we mean I/O channel layers. this is the Tcl Library Procedures page for Tcl_StackChannel(3tcl) and honestly? it's giving main character energy. 🦋

---

✨ NAME ✨

Tcl_StackChannel, Tcl_UnstackChannel, Tcl_GetStackedChannel, Tcl_GetTopChannel — manipulate stacked I/O channels 💅

---

🌸 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 we yell at when something goes wrong, aka error reporting. 😭
• const Tcl_ChannelType *typePtr (in) — the brand new channel I/O procedures to use for channel. new fit, same girl.
• void *clientData (in) — an arbitrary one-word value that gets passed along to the channel I/O procedures. it's a lil gift 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. note that this can be a subset of the operations currently allowed on channel — you can absolutely downgrade, no shame. 👑
• Tcl_Channel channel (in) — an existing Tcl channel, like the kind Tcl_CreateChannel hands you.

---

🦋 DESCRIPTION 🦋

so these functions are literally for extensions that add processing layers to Tcl I/O channels. think compression modules, encryption modules — the whole "wrap a vibe around another vibe" situation. these functions transparently stack and unstack a new channel on top of an existing one, and bestie, any number of channels can be stacked together. it's a tower. it's a stack. it's iconic. 💅

the Tcl_ChannelType version currently supported is TCL_CHANNEL_VERSION_5. for the details, go look at Tcl_CreateChannel. no cap.

Tcl_StackChannel stacks a new channel on an existing channel, using the same name that was registered for channel by Tcl_RegisterChannel.

how does Tcl_StackChannel do it? it creates a new channel structure and places itself on top of the channel stack. now 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 up at the top of the channel stack. a pointer to the new top channel structure gets returned. and if an error happens while stacking? you get NULL instead. 🙈

the mask parameter says which operations are allowed on the new channel, and — say it with me — 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. character development, honestly. 💖

closing a channel closes the channels stacked below it. and the close of stacked channels is executed in a way that allows buffered data to be properly flushed — so nothing gets ghosted, everything gets written out. periodt. ✨

Tcl_UnstackChannel reverses the whole process. the old channel gets associated with the channel name again, and the processing module that Tcl_StackChannel added is destroyed. if there is no old channel, then Tcl_UnstackChannel is equivalent to Tcl_Close. and if an error occurs while unstacking, you get TCL_ERROR back; otherwise you get TCL_OK. simple as. 🍓

Tcl_GetTopChannel returns the top channel in the stack of channels that the supplied channel is part of. 👑

Tcl_GetStackedChannel returns the channel in the stack of channels that's just below the supplied channel. the supportive bestie underneath. 🫶

---

🌈 SEE ALSO 🌈

• Notifier(3tcl)
• Tcl_CreateChannel(3tcl)
• Tcl_OpenFileChannel(3tcl)
• vwait(3tcl)

---

⭐ KEYWORDS ⭐

channel, compression

---

and that's the whole page, bestie — brought to you by Tcl 8.3, landing in your terminal with all the stacked-channel lore you could ever need. go forth and stack responsibly. 💜✨🎀