NAME

       TCL_MEM_DEBUG  -  Compile-time  flag  to enable Tcl memory
       debugging.


DESCRIPTION

       When Tcl is compiled with TCL_MEM_DEBUG defined, a  power­
       ful  set of memory debugging aids are included in the com­
       piled binary.  This includes C and Tcl functions which can
       aid  with  debugging memory leaks, memory allocation over­
       runs, 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 com­
       pile 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_DumpActive­
       Memory, 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 size of the guard zone is
       defined   by   the   C   #define   GUARD_SIZE   in   base­
       line/src/ckalloc.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  con­
       tents 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.

       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 corrup­
       tion  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


Man(1) output converted with man2html