NAME¶
TCL_MEM_DEBUG - Compile-time flag to enable Tcl memory debugging
DESCRIPTION¶
When Tcl is compiled with
TCL_MEM_DEBUG defined, a powerful set of memory
debugging aids is 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 (e.g. by passing the
--enable-symbols=mem
flag to the
configure script when building). 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
Tcl_DbCkfree and
Tcl_DbCkalloc or
Tcl_Alloc and
Tcl_Free 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 sizes of the guard zones are defined by the C
#define
LOW_GUARD_SIZE and #define
HIGH_GUARD_SIZE in the file
generic/tclCkalloc.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 is not 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¶
ckalloc, memory, Tcl_ValidateAllMemory, Tcl_DumpActiveMemory
KEYWORDS¶
memory, debug