Tcl_GetStdChannel(3tcl)

💖 Tcl_GetStdChannel — bestie edition 💖

okay so we're in the Tcl Library Procedures section of the manual, page Tcl_GetStdChannel(3tcl), and honestly? this one is a whole vibe. it's about the three channels every Tcl program is lowkey obsessed with. let's get into it 🫶

---

✨ NAME ✨

Tcl_GetStdChannel, Tcl_SetStdChannel — the procedures for retrieving and replacing the standard channels. that's it, that's the job. two little functions, one big responsibility 💅

---

🌸 SYNOPSIS 🌸

#include <tcl.h>

Tcl_Channel
Tcl_GetStdChannel(type)

Tcl_SetStdChannel(channel, type)

---

🎀 ARGUMENTS 🎀

• int type (in) — the identifier for the standard channel you wanna grab or mess with. it MUST be one of TCL_STDIN, TCL_STDOUT, or TCL_STDERR. no other values, bestie, don't try it 🙈
• Tcl_Channel channel (in) — the channel that becomes the new value for whichever standard channel you picked.

---

🦋 DESCRIPTION 🦋

Tcl defines three special channels that all the I/O-related commands fall back on when you don't specify some other channel. think of them as the main characters of your program's input/output life 👑

• the standard input channel is named stdin, and read and gets use it
• the standard output channel is named stdout, and puts uses it
• the standard error channel is named stderr, and it's the one that reports errors

plus — and this is the part people forget — these standard channels get inherited by any child processes you create with exec or open, as long as you didn't do any other redirections. so they're literally passing the vibe down to the next generation ✨

the thing is, the standard channels are actually aliases for other normal channels. so the channel currently sitting behind a standard channel is whatever it is at that moment. to find out, call Tcl_GetStdChannel with one of TCL_STDIN, TCL_STDOUT, or TCL_STDERR as the type. what comes back is either a valid channel or NULL. no in-between, no surprises 💀

want to swap one out? call Tcl_SetStdChannel with a new channel — or NULL — in the channel argument, and whatever standard channel type points at gets replaced. and here's a lil caveat: if that channel later gets closed by a call to Tcl_Close, then the matching standard channel automatically becomes NULL. it doesn't cling, it moves on. queen behavior honestly 💅

now, if you're passing a non-NULL channel to Tcl_SetStdChannel, then that exact same value should also go to Tcl_RegisterChannel, like this:

Tcl_RegisterChannel(NULL, channel);

why?? because Tcl_SetStdChannel has a misfeature — it fails to do some reference counting housekeeping 😭 and we can't just fix it either, because fixing it would contradict the assumptions of some existing code that already calls Tcl_SetStdChannel. so the workaround is the move. it's giving "we know, we know, just do this." no cap.

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 🧚
• if Tcl_SetStdChannel gets called before Tcl_GetStdChannel, then the default channel will not be created. order matters, bestie ⭐

and if one of the standard channels ends up as NULL — whether because you passed a NULL channel to Tcl_SetStdChannel, or because you called Tcl_Close on it — then the next call to Tcl_CreateChannel will automatically slot the newly created channel into that standard channel. it just fills the empty seat 🌈

and if more than one standard channel is NULL? then they get assigned in order, starting with standard input, then standard output, and standard error goes last. queue up, girlies, we're going in order 🎀

if you want the full deep dive on standard channels and how the Tcl library behaves around them, go read Tcl_StandardChannels. it's the whole treatise. iykyk 📚

---

💜 SEE ALSO 💜

• Tcl_Close(3tcl)
• Tcl_CreateChannel(3tcl)
• Tcl_Main(3tcl)
• tclsh(1)

---

⭐ KEYWORDS ⭐

standard channel, standard input, standard output, standard error

---

and that's the page, bestie!! this one's from the Tcl library docs, version 7.5 — so like, vintage but still iconic, fr fr. go forth and handle your channels responsibly 👑💖🎀