1TCL_MEM_DEBUG(3)            Tcl Library Procedures            TCL_MEM_DEBUG(3)
2
3
4
5______________________________________________________________________________
6

NAME

8       TCL_MEM_DEBUG - Compile-time flag to enable Tcl memory debugging
9______________________________________________________________________________
10

DESCRIPTION

12       When Tcl is compiled with TCL_MEM_DEBUG defined, a powerful set of mem‐
13       ory debugging aids is included in the compiled binary.  This includes C
14       and  Tcl  functions  which  can aid with debugging memory leaks, memory
15       allocation overruns, and other memory related errors.
16

ENABLING MEMORY DEBUGGING

18       To enable memory debugging, Tcl should be recompiled from scratch  with
19       TCL_MEM_DEBUG defined (e.g. by passing the --enable-symbols=mem flag to
20       the configure script when building).  This will also compile in a  non-
21       stub version of Tcl_InitMemory to add the memory command to Tcl.
22
23       TCL_MEM_DEBUG  must be either left defined for all modules or undefined
24       for all modules that are going to be linked together.  If they are not,
25       link  errors  will occur, with either Tcl_DbCkfree and Tcl_DbCkalloc or
26       Tcl_Alloc and Tcl_Free being undefined.
27
28       Once memory debugging support has been compiled into Tcl, the  C  func‐
29       tions Tcl_ValidateAllMemory, and Tcl_DumpActiveMemory, and the Tcl mem‐
30       ory command can be used to validate and examine memory usage.
31

GUARD ZONES

33       When memory debugging is enabled, whenever a call to ckalloc  is  made,
34       slightly  more  memory than requested is allocated so the memory debug‐
35       ging code can keep track of the allocated memory, and eight-byte “guard
36       zones”  are  placed  in  front  of  and  behind  the space that will be
37       returned to the caller.  (The sizes of the guard zones are  defined  by
38       the  C  #define  LOW_GUARD_SIZE and #define HIGH_GUARD_SIZE in the file
39       generic/tclCkalloc.c — it can be extended if you  suspect  large  over‐
40       write problems, at some cost in performance.)  A known pattern is writ‐
41       ten into the guard zones and, on a call to ckfree, the guard  zones  of
42       the  space being freed are checked to see if either zone has been modi‐
43       fied in any way.  If one has been, the guard bytes and their  new  con‐
44       tents  are  identified, and a “low guard failed” or “high guard failed”
45       message is issued.  The “guard failed” message includes the address  of
46       the  memory  packet  and the file name and line number of the code that
47       called ckfree.  This allows you to detect the common sorts  of  one-off
48       problems,  where  not  enough  space  was allocated to contain the data
49       written, for example.
50

DEBUGGING DIFFICULT MEMORY CORRUPTION PROBLEMS

52       Normally, Tcl compiled with memory debugging enabled will make it  easy
53       to isolate a corruption problem.  Turning on memory validation with the
54       memory command can help isolate difficult problems.  If you suspect (or
55       know)  that corruption is occurring before the Tcl interpreter comes up
56       far enough for you to issue commands, you can set MEM_VALIDATE  define,
57       recompile  tclCkalloc.c and rebuild Tcl.  This will enable memory vali‐
58       dation from the first call to ckalloc, again, at  a  large  performance
59       impact.
60
61       If you are desperate and validating memory on every call to ckalloc and
62       ckfree is not enough, you  can  explicitly  call  Tcl_ValidateAllMemory
63       directly at any point.  It takes a char * and an int which are normally
64       the filename and line number of the caller, but they  can  actually  be
65       anything  you  want.   Remember  to remove the calls after you find the
66       problem.
67

SEE ALSO

69       ckalloc, memory, Tcl_ValidateAllMemory, Tcl_DumpActiveMemory
70

KEYWORDS

72       memory, debug
73
74
75
76Tcl                                   8.1                     TCL_MEM_DEBUG(3)
Impressum