This document is a Mac OS X manual page. Manual pages are a command-line technology for providing documentation. You can view these manual pages locally using the man(1) command. These manual pages come from many different sources, and thus, have a variety of writing styles.

This manual page is associated with the Mac OS X developer tools. The software or headers described may not be present on your Mac OS X installation until you install the developer tools package. This package is available on your Mac OS X installation DVD, and the latest versions can be downloaded from developer.apple.com.

For more information about the manual page format, see the manual page for manpages(5).

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 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  prob-lem. problem.
       lem.   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(3)