TCL_MEM_DEBUG(3tcl)

💖 TCL_MEM_DEBUG 💖

okay bestie, gather round, because this one is the compile-time flag that unlocks the whole memory-debugging wonderland in Tcl. It's called TCL_MEM_DEBUG and yes, it's exactly as iconic as it sounds. 🎀

---

✨ DESCRIPTION ✨

So here's the tea 🍓: when Tcl gets compiled with TCL_MEM_DEBUG defined, a whole powerful set of memory debugging aids gets baked right into the compiled binary. Not a plugin, not an add-on — in the binary, bestie.

That includes C functions and Tcl functions that can help you debug:

• memory leaks 🫠
• memory allocation overruns 😭
• and other memory-related errors 💀

It's giving "I brought backup." Periodt.

---

🌈 ENABLING MEMORY DEBUGGING 🌈

To turn memory debugging on, Tcl needs to be recompiled from scratch with TCL_MEM_DEBUG defined. Easiest slay: pass the --enable-symbols=mem flag to the configure script when you're building. ✨

Doing that also compiles in a non-stub version of Tcl_InitMemory, which is what adds the memory command to Tcl. So you get the command and the flag. Two birds, one vibe check. 🦋

⚠️ BIG ONE, no cap: TCL_MEM_DEBUG must be either left defined for all modules or undefined for all modules that are going to be linked together. Do not mix. If you mix them, you get link errors — specifically either Tcl_DbCkfree and Tcl_DbCkalloc or Tcl_Alloc and Tcl_Free coming up undefined. It's giving chaos and we don't want that. 💅

Once memory debugging support is compiled into Tcl, you've got these in your toolkit:

• the C function Tcl_ValidateAllMemory
• the C function Tcl_DumpActiveMemory
• the Tcl memory command

Use them to validate and examine memory usage. Obsessed. 💜

---

🛡️ GUARD ZONES 🛡️

Okay so this part is genuinely so clever. When memory debugging is enabled, every call to Tcl_Alloc allocates slightly more memory than you actually requested, so the memory debugging code can keep track of the allocated memory. Then it places eight-byte "guard zones" in front of and behind the space that gets returned to the caller. 🌸

The sizes of those guard zones are defined by the C

#define LOW_GUARD_SIZE
#define HIGH_GUARD_SIZE

in the file generic/tclCkalloc.c — and yes, you can extend them if you suspect large overwrite problems, though it comes at some cost in performance. Lowkey a tradeoff, highkey worth it when you're desperate. 🧚

A known pattern gets written into the guard zones. Then, on a call to Tcl_Free, the guard zones of the space being freed are checked to see if either zone has been modified in any way. 🔍

If one has been:

• the guard bytes and their new contents are identified
• a "low guard failed" or "high guard failed" message is issued 🚨

And that "guard failed" message is so helpful, bestie — it includes:

• the address of the memory packet
• the file name and line number of the code that called Tcl_Free

Which means you can detect the common sorts of one-off problems, like when not enough space was allocated to contain the data that got written. Iconic. Ate. 👑

---

😭 DEBUGGING DIFFICULT MEMORY CORRUPTION PROBLEMS 😭

Normally, Tcl compiled with memory debugging enabled makes it pretty easy to isolate a corruption problem. And turning on memory validation with the memory command can help isolate the difficult ones. 🫶

But now the scary part. If you suspect (or straight up know) that corruption is happening before the Tcl interpreter comes up far enough for you to even issue commands? Yeah. Then you can:

1. set the MEM_VALIDATE define
2. recompile tclCkalloc.c
3. rebuild Tcl

That enables memory validation from the first call to Tcl_Alloc. But — and this is the fine print — it comes again at a large performance impact. 💀 Consider yourself warned.

And if you are truly desperate and validating memory on every single call to Tcl_Alloc and Tcl_Free still isn't enough? You can explicitly call Tcl_ValidateAllMemory directly at any point. 🫡

It takes a char * and an int, which are normally the filename and line number of the caller — but honestly they can be anything you want. No rules, main character energy.

🚨 Bestie, remember to remove those calls after you find the problem. Do not leave them in. Please. I'm begging. 🙈

---

👀 SEE ALSO 👀

Tcl_Alloc, memory, Tcl_ValidateAllMemory, Tcl_DumpActiveMemory

---

🔑 KEYWORDS 🔑

memory, debug

---

and that's the whole page, bestie!! 💖✨ this one shipped with Tcl 8.1, it's part of the Tcl Library Procedures (that's the 3tcl manual section, iykyk), and it's dated 8.1 — so go forth, enable TCL_MEM_DEBUG, and catch those overruns. slay 🎀🦋💅