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
       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_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  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

       ckalloc, memory, Tcl_ValidateAllMemory, Tcl_DumpActiveMemory

KEYWORDS

       memory, debug