Tcl_GetStdChannel(3)

✨ NAME ✨

Tcl_GetStdChannel, Tcl_SetStdChannel — the procedures for grabbing the standard channels and swapping them out 💅

This is the Tcl Library Procedures page, bestie, and yes we're doing the whole thing 🫶

---

🌸 SYNOPSIS 🌸

#include <tcl.h>

Tcl_Channel
Tcl_GetStdChannel(type)

Tcl_SetStdChannel(channel, type)

---

🎀 ARGUMENTS 🎀

• int type (in) — the identifier for whichever standard channel you're trying to retrieve or mess with. It must be one of TCL_STDIN, TCL_STDOUT, or TCL_STDERR. No other values, okay? Not negotiable 🔥
• Tcl_Channel channel (in) — the channel that becomes the new value of the standard channel you picked.

---

💖 DESCRIPTION 💖

So Tcl has three special channels that all the I/O-ish commands fall back on when you don't name a channel yourself. Iconic behaviour, honestly.

• The standard input channel is named stdin and it's what read and gets use.
• The standard output channel is named stdout and it's what puts uses.
• The standard error channel is named stderr and it's the one for reporting errors.

And on top of that? The standard channels get inherited by any child processes created with exec or open when there aren't any other redirections in play. The vibes pass down, periodt.

Okay but here's the tea: the standard channels are actually aliases for other normal channels. It's giving understudy energy. To find out which channel is currently playing the role, call Tcl_GetStdChannel with one of TCL_STDIN, TCL_STDOUT, or TCL_STDERR as the type. What you get back is either a valid channel or NULL — and NULL is a whole mood, it means nothing's there 😭

You can also cast a new channel in the role: call Tcl_SetStdChannel with your new channel — or NULL — in the channel argument, for the standard channel named by type. And if that channel later gets closed by a call to Tcl_Close, the matching standard channel automatically flips itself to NULL. Self-cleaning, we love to see it ✨

Now for the messy part 🙈 If you pass a non-NULL value for channel to Tcl_SetStdChannel, then you should pass that same value to Tcl_RegisterChannel, like this:

Tcl_RegisterChannel(NULL, channel);

This is a workaround for a misfeature in Tcl_SetStdChannel: it fails to do some reference counting housekeeping. And no, that misfeature cannot be corrected without contradicting the assumptions of some existing code that calls Tcl_SetStdChannel. So we live with it. Character development, I guess 💀

More lore: if Tcl_GetStdChannel gets called before Tcl_SetStdChannel, Tcl will construct a brand new channel to wrap the appropriate platform-specific standard file handle. But if Tcl_SetStdChannel is called before Tcl_GetStdChannel, then that default channel will not be created. Order matters, bestie, always has 🌈

If one of the standard channels is set to NULL — whether by calling Tcl_SetStdChannel with a NULL channel argument, or by calling Tcl_Close on the channel — then the next call to Tcl_CreateChannel automatically sets that standard channel to the newly created channel. Chef's kiss 🧚

And if more than one standard channel is NULL? Then they get assigned in this exact order:

1. standard input first
2. standard output next
3. standard error last

No queue-jumping 💅

Oh and if you want the full general treatise about standard channels and how the Tcl library behaves around them, go read Tcl_StandardChannels. It's the deep lore 🦋

---

👑 SEE ALSO 👑

Tcl_Close(3), Tcl_CreateChannel(3), Tcl_Main(3), tclsh(1)

---

⭐ KEYWORDS ⭐

standard channel, standard input, standard output, standard error

---

and that's the whole page, bestie 💖 This was the Tcl_GetStdChannel(3) page from Tcl 7.5 — mwah, go forth and channel responsibly 🎀🫶