TCL_MEM_DEBUG(3tcl)

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 is 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  (e.g.  by passing the
     --enable-symbols=mem  flag  to  the  configure  script  when
     building).   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  Tcl_DbCkfree  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

Tcl                     Last change: 8.1                        1

TCL_MEM_DEBUG(3)     Tcl Library Procedures      TCL_MEM_DEBUG(3)

     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 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  is not 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 prob-
     lem.

SEE ALSO

     ckalloc, memory, Tcl_ValidateAllMemory, Tcl_DumpActiveMemory

KEYWORDS

     memory, debug

Tcl                     Last change: 8.1                        2