TCL_MEM_DEBUG(3)					      Tcl Library Procedures						  TCL_MEM_DEBUG(3)

__________________________________________________________________________________________________________________________________________________

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_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 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 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 writ-
       ten 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 mod-
       ified 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  con-
       tain 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

       memory, Tcl_ValidateAllMemory, Tcl_DumpActiveMemory

KEYWORDS

       memory, debug

Tcl									8.1							  TCL_MEM_DEBUG(3)