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

Tcl                                                    8.1                                   TCL_MEM_DEBUG(3tcl)