TCL_MEM_DEBUG()

Compile-time flag to enable Tcl memory debugging 

Tcl Library Procedures

DESCRIPTION

When Tcl is compiled with TCL_MEM_DEBUG() defined, a powerful set of memory debugging aids are included in the compiled binary. This includes C and Tcl functions which can aid with debugging memory leaks, memory allocation overruns, and other memory related errors.

ENABLING MEMORY DEBUGGING

To enable memory debugging, Tcl should be recompiled from scratch with TCL_MEM_DEBUG() defined. This will also compile in a non-stub version of Tcl_InitMemory() to add the memory command to Tcl.

TCL_MEM_DEBUG() must be either left defined for all modules or undefined for all modules that are going to be linked together. If they are not, link errors will occur, with either TclDbCkfree and Tcl_DbCkalloc or Tcl_Ckalloc and Tcl_Ckfree being undefined.

Once memory debugging support has been compiled into Tcl, the C functions Tcl_ValidateAllMemory(), and Tcl_DumpActiveMemory(), and the Tcl memory command can be used to validate and examine memory usage.

GUARD ZONES

When memory debugging is enabled, whenever a call to ckalloc is made, slightly more memory than requested is allocated so the memory debugging code can keep track of the allocated memory, and eight-byte guard zones are placed in front of and behind the space that will be returned to the caller. (The size of the guard zone is defined by the C #define GUARD_SIZE in baseline/src/ckalloc.c -- it can be extended if you suspect large overwrite problems, at some cost in performance.) A known pattern is written into the guard zones and, on a call to ckfree, 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, and a low guard failed or high guard failed message is issued. The guard failed message includes the address of the memory packet and the file name and line number of the code that called ckfree. This allows you to detect the common sorts of one-off problems, where not enough space was allocated to contain the data written, for example.

DEBUGGING DIFFICULT MEMORY CORRUPTION PROBLEMS

Normally, Tcl compiled with memory debugging enabled will make it easy to isolate a corruption problem. Turning on memory validation with the memory command can help isolate difficult problems. If you suspect (or know) that corruption is occurring before the Tcl interpreter comes up far enough for you to issue commands, you can set MEM_VALIDATE define, recompile tclCkalloc.c and rebuild Tcl. This will enable memory validation from the first call to ckalloc, again, at a large performance impact.

If you are desperate and validating memory on every call to ckalloc and ckfree 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 they can actually be anything you want. Remember to remove the calls after you find the problem.

PORTABILITY

Windows 10. Windows Server 2016. Windows Server 2019. Windows 11. Windows Server 2022. Windows Server 2025.

AVAILABILITY

PTC MKS Toolkit for Professional Developers
PTC MKS Toolkit for Enterprise Developers
PTC MKS Toolkit for Enterprise Developers 64-Bit Edition

SEE ALSO

Commands:
memory

Functions:
Tcl_DumpActiveMemory(), Tcl_ValidateAllMemory()

PTC MKS Toolkit 10.5 Documentation Build 40.