Tcl_Alloc(3tcl)

💖 NAME 💖

Tcl_Alloc, Tcl_Free, Tcl_Realloc, Tcl_AttemptAlloc, Tcl_AttemptRealloc, Tcl_GetMemoryInfo — bestie, these are the girls who allocate and free heap memory 💅

So this is a page from the Tcl Library Procedures manual, and honestly? It's giving memory-management main character energy. Let's get into it ✨

---

🌸 SYNOPSIS 🌸

#include <tcl.h>

void *
Tcl_Alloc(size)

Tcl_Free(ptr)

void *
Tcl_Realloc(ptr, size)

void *
Tcl_AttemptAlloc(size)

void *
Tcl_AttemptRealloc(ptr, size)

Tcl_GetMemoryInfo(dsPtr)

---

🎀 ARGUMENTS 🎀

• size_t size (in) — the size in bytes of the memory block you wanna allocate. Like how many bytes, gorl.
• void *ptr (in) — pointer to the memory block you're freeing or realloc'ing.
• Tcl_DString *dsPtr (in) — an initialized DString pointer. Yes it has to be initialized already, we don't do uninitialized in this house 🙈

---

✨ DESCRIPTION ✨

Okay so here's the tea ☕: these procedures give you a platform and compiler independent interface for memory allocation. If your program needs to hand off ownership of memory blocks between Tcl and other modules, you use these routines — not the native malloc() and free() from the C run-time library. No cap.

• Tcl_Alloc returns a pointer to a block of at least size bytes, suitably aligned for any use. Any use. She's versatile like that 💅
• Tcl_Free makes the space referred to by ptr available for further allocation. She's done, she's releasing, she's moving on 🦋
• Tcl_Realloc changes the size of the block pointed to by ptr to size bytes and returns a pointer to the new block. The contents stay unchanged up to the lesser of the new and old sizes. Heads up tho — the returned location may be different from ptr. If ptr is NULL, this is equivalent to calling Tcl_Alloc with just the size argument. Glow-up or relocation, either way she ate 🔥
• Tcl_AttemptAlloc and Tcl_AttemptRealloc are identical in function to Tcl_Alloc and Tcl_Realloc, except — and this is the important part — they will not cause the Tcl interpreter to panic if the memory allocation fails. If the allocation fails, these functions return NULL. Lowkey chill about it, highkey useful 😌

Note that on some platforms, but not all, attempting to allocate a zero-sized block of memory will also cause these functions to return NULL. So like… zero bytes, zero vibes, sometimes zero pointer. Not everywhere tho. iykyk 💀

When a module or Tcl itself is compiled with TCL_MEM_DEBUG defined, the procedures Tcl_Alloc, Tcl_Free, Tcl_Realloc, Tcl_AttemptAlloc, and Tcl_AttempRealloc are implemented as macros, redefined to be special debugging versions of these procedures. (Yes, that spelling is exactly what the page says. We do not fix the source material, we respect the source material 🫶)

Tcl_GetMemoryInfo appends a list-of-lists of memory stats to the provided DString. But listen — this function cannot be used in stub-enabled extensions, and it is only available if Tcl is compiled with the threaded memory allocator. When used in stub-enabled embedders, the stubs table must be first initialized using one of Tcl_InitSubsystems, Tcl_SetPanicProc, Tcl_FindExecutable or TclZipfs_AppHook. Read that twice bestie, it's a whole prerequisite situation 👑

---

👑 KEYWORDS 👑

alloc, allocation, free, malloc, memory, realloc, TCL_MEM_DEBUG

---

That's the whole page, you're officially fluent in Tcl heap memory 🌈

This was pulled from Tcl 9.0 — so like, that's the version, that's the source, that's the moment. Thanks for reading with me, bestie, mwah 💖 🎀 🦋 ✨