Tcl_DetachPids(3tcl)

✨ Tcl_DetachPids — the "bestie, hold my child processes" era ✨

okay so this is a page straight out of the Tcl Library Procedures manual, and it's all about managing child processes in background. it's giving very much "i made a subprocess and now i don't want to think about it ever again" energy, and honestly? relatable. let's get into it 💅

---

🌸 SYNOPSIS 🌸

like, here's the vibe, literally verbatim:

#include <tcl.h>

Tcl_DetachPids(numPids, pidPtr)

Tcl_ReapDetachedProcs()

Tcl_Pid
Tcl_WaitPid(pid, statusPtr, options)

---

🎀 ARGUMENTS 🎀

• Tcl_Size numPids (in) — how many process ids are chillin' inside the array that pidPtr points at. that's the count, bestie.
• int *pidPtr (in) — the address of the array holding all numPids of those process ids. yes, it's an array of ints, we love a pointer moment 🫶
• Tcl_Pid pid (in) — the id of the process (pipe) we're waiting on. the one we're clocking. the main character.
• int *statusPtr (out) — where the result of waiting on a process (pipe) goes. it's either 0 or ECHILD. that's it. that's the whole range. iconically minimal.
• int options (in) — the options controlling the wait. WNOHANG means "do NOT wait while checking the process" — like, peek, don't linger. 🙈

---

💖 DESCRIPTION 💖

Tcl_DetachPids and Tcl_ReapDetachedProcs are the whole mechanism for managing subprocesses that are running in the background. so why do these even exist? because the parent of a process eventually has to invoke the waitpid kernel call (or one of a few other similar kernel calls) to wait for the child to exit. that's not optional, it's the rules.

and until the parent actually waits for the child, the child's state cannot be completely reclaimed by the system. so if a parent keeps making children and never waits on them, the system's process table will eventually overflow — even if every single one of those children has already exited. 💀 yes, even the dead ones. the ghost processes are still taking up room. it's giving haunted house.

Tcl_DetachPids is the "please take this off my plate" function. you call it to ask Tcl to take responsibility for one or more processes whose process ids live in the pidPtr array you passed as an argument. the caller has presumably already started these processes running in the background and does not want to deal with them ever again. no thoughts, head empty, Tcl's problem now. ✨

Tcl_ReapDetachedProcs is the cleanup crew. it invokes the waitpid kernel call on each of the background processes so that its state can be cleaned up if it has exited. and if a process hasn't exited yet? Tcl_ReapDetachedProcs does not wait for it to exit — it'll just check again the next time it gets invoked. no camping out, no standing around. very efficient of it honestly.

here's the slay part: Tcl automatically calls Tcl_ReapDetachedProcs each time the exec command is executed. so in most cases, no code outside of Tcl needs to call Tcl_ReapDetachedProcs at all. it just handles itself. lowkey self-sufficient queen. 👑

but — and this is the important part — if you call Tcl_DetachPids in situations where the exec command may never get executed, you may wish to call Tcl_ReapDetachedProcs from time to time so that background processes can actually get cleaned up. so like, don't just leave them there forever, bestie. 🫶

and Tcl_WaitPid? it's a thin wrapper around the facilities the operating system provides, used to wait on the end of a spawned process and to check whether a spawned process is still running. it's used by Tcl_ReapDetachedProcs and the channel system to portably access the operating system. so it's the middleman, and it's doing a great job. 🌈

---

🦋 KEYWORDS 🦋

background, child, detach, process, wait

---

and that's the whole page, fr fr. this one came to you from the Tcl manual, page Tcl_DetachPids(3tcl) — go forth, detach those pids, and reap them responsibly. periodt. 💖✨🎀