2. EL 7
  3. tcl
  4. TCL_MEM_DEBUG(3)

Scroll to navigation

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_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 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 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 problem.






SEE ALSO


ckalloc, memory, Tcl_ValidateAllMemory, Tcl_DumpActiveMemory






KEYWORDS


memory, debug







  

    8.1
    Tcl