Manual Pages for UNIX Operating System command usage for man TCL_MEM_DEBUG

Tcl Library Procedures                        TCL_MEM_DEBUG(3TCL)



_________________________________________________________________

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



Tcl                     Last change: 8.1                        1






Tcl Library Procedures                        TCL_MEM_DEBUG(3TCL)



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


SEE ALSO
     ckalloc, memory, Tcl_ValidateAllMemory, Tcl_DumpActiveMemory


KEYWORDS
     memory, debug



ATTRIBUTES
     See attributes(5) for descriptions of the  following  attri-
     butes:

     _______________________________________
    |   ATTRIBUTE TYPE   |  ATTRIBUTE VALUE|
    |____________________|__________________|_
    | Availability       |  runtime/tcl-8  |
    |____________________|__________________|_
    | Interface Stability|  Uncommitted    |
    |____________________|_________________|

NOTES
     Source for Tcl is available on http://opensolaris.org.







Tcl                     Last change: 8.1                        2