TCL_MEM_DEBUG(3) Tcl Library Procedures TCL_MEM_DEBUG(3)______________________________________________________________________________NAMETCL_MEM_DEBUG - Compile-time flag to enable Tcl memory debugging.
DESCRIPTION
When Tcl is compiled with TCL_MEM_DEBUG defined, a powerful set of mem‐
ory 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 func‐
tions Tcl_ValidateAllMemory, and Tcl_DumpActiveMemory, and the Tcl mem‐
ory 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 debug‐
ging 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 per‐
formance.) 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 vali‐
dation 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.
SEE ALSO
memory, Tcl_ValidateAllMemory, Tcl_DumpActiveMemory
KEYWORDS
memory, debug
ATTRIBUTES
See attributes(5) for descriptions of the following attributes:
┌────────────────────┬─────────────────┐
│ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
├────────────────────┼─────────────────┤
│Availability │ SUNWTcl │
├────────────────────┼─────────────────┤
│Interface Stability │ External │
└────────────────────┴─────────────────┘
NOTES
Source for Tcl is available in the SUNWTclS package.
Tcl 8.1 TCL_MEM_DEBUG(3)
