process(3tcl)

🎀 process(3tcl) 🎀

okay bestie, welcome to tcl::process — a built-in command in the Tcl Built-In Commands manual, and honestly? it's giving subprocess manager, main character energy. it's the girl who keeps track of every lil child process you spawn. 💅

---

✨ NAME ✨

tcl::process — subprocess management 🫶

---

🌸 SYNOPSIS 🌸

::tcl::process option ?arg arg ...?

---

💖 DESCRIPTION 💖

so this command is literally your way to manage the subprocesses that open and exec create — and you find them by their process identifiers (PIDs), iykyk. the legal options (which may be abbreviated, so you can be lazy, we support that) are:

• ::tcl::process autopurge ?flag? — the automatic purge facility, aka the girl who cleans up after the party. if flag is specified as a boolean value, it activates or deactivates autopurge. and in all cases, it returns the current status as a boolean value. when autopurge is active, Tcl_ReapDetachedProcs gets called each time the exec command is executed or a pipe channel created by open is closed. when autopurge is inactive, you have to call ::tcl::process purge explicitly — no free rides. by default, autopurge is active. periodt.
• ::tcl::process list — returns the list of subprocess PIDs. this includes all currently executing subprocesses and all terminated subprocesses that have not yet had their corresponding process table entries purged. yes, the ghosts are still on the list until someone reaps them. 👻
• ::tcl::process purge ?pids? — cleans up all data associated with terminated subprocesses. if pids is specified as a list of PIDs, the command only cleans up data for the matching subprocesses, if they exist. if a process listed is still active, this command does nothing to that process (she's still busy, leave her alone). any PID that does not correspond to a subprocess is ignored.
• ::tcl::process status ?switches? ?pids? — returns a dictionary mapping subprocess PIDs to their respective status. if pids is specified as a list of PIDs, the command only returns the status of the matching subprocesses, if they exist. any PID that does not correspond to a subprocess is ignored. for active processes, the status is an empty value. for terminated processes, the status is a list with the following format: {code ?msg errorCode?}, where:
  • code — is a standard Tcl return code, i.e., 0 for TCL_OK and 1 for TCL_ERROR,
  • msg — is the human-readable error message,
  • errorCode — uses the same format as the errorCode global variable

ngl, msg and errorCode are only present for abnormally terminated processes (i.e. those where the code is nonzero). and under the hood? this command calls Tcl_WaitPid with the WNOHANG flag set for non-blocking behavior — unless the -wait switch is set (see below, bestie, keep reading).

additionally, ::tcl::process status accepts the following switches:

• -wait — by default the command returns immediately (the underlying Tcl_WaitPid is called with the WNOHANG flag set) unless this switch is set. if pids is specified as a list of PIDs, the command waits until the status of the matching subprocesses are available. if pids was not specified, this command will wait for all known subprocesses. she will literally sit there and wait. loyalty. 🫡
• -- — marks the end of switches. the argument following this one will be treated as the first arg even if it starts with a -. iconic protective behavior.

---

🔥 EXAMPLES 🔥

these show the use of ::tcl::process. some of the results from ::tcl::process status are split over multiple lines for readability (not because they're being dramatic, promise).

::tcl::process autopurge
     → true
::tcl::process autopurge false
     → false

set pid1 [exec command1 a b c | command2 d e f &]
     → 123 456
set chan [open "|command1 a b c | command2 d e f"]
     → file123
set pid2 [pid $chan]
     → 789 1011

::tcl::process list
     → 123 456 789 1011

::tcl::process status
     → 123 0
       456 {1 "child killed: write on pipe with no readers" {
         CHILDKILLED 456 SIGPIPE "write on pipe with no readers"}}
       789 {1 "child suspended: background tty read" {
         CHILDSUSP 789 SIGTTIN "background tty read"}}
       1011 {}

::tcl::process status 123
     → 123 0

::tcl::process status 1011
     → 1011 {}

::tcl::process status -wait
     → 123 0
       456 {1 "child killed: write on pipe with no readers" {
         CHILDKILLED 456 SIGPIPE "write on pipe with no readers"}}
       789 {1 "child suspended: background tty read" {
         CHILDSUSP 789 SIGTTIN "background tty read"}}
       1011 {1 "child process exited abnormally" {
         CHILDSTATUS 1011 -1}}

::tcl::process status 1011
     → 1011 {1 "child process exited abnormally" {
         CHILDSTATUS 1011 -1}}

::tcl::process purge
exec command1 1 2 3 &
     → 1213
::tcl::process list
     → 1213

---

🦋 SEE ALSO 🦋

exec(3tcl), open(3tcl), pid(3tcl), Tcl_DetachPids(3tcl), Tcl_WaitPid(3tcl), Tcl_ReapDetachedProcs(3tcl)

go read those too, they're the friend group. 💜

---

⭐ KEYWORDS ⭐

background, child, detach, process, wait

---

okay that's the whole page, bestie, no cap. this one's from Tcl 9.0, and the page is process(3tcl) — go forth and manage your subprocesses, you absolute queen. 👑✨