1TCL_MEM_DEBUG(3) Tcl Library Procedures TCL_MEM_DEBUG(3)
2______________________________________________________________________________
6
8 TCL_MEM_DEBUG - Compile-time flag to enable Tcl memory debugging.
9_________________________________________________________________
10
13 When Tcl is compiled with TCL_MEM_DEBUG defined, a powerful set of mem‐
14 ory debugging aids are included in the compiled binary. This includes
15 C and Tcl functions which can aid with debugging memory leaks, memory
16 allocation overruns, and other memory related errors.
17
20 To enable memory debugging, Tcl should be recompiled from scratch with
21 TCL_MEM_DEBUG defined. This will also compile in a non-stub version of
22 Tcl_InitMemory to add the memory command to Tcl.
23 TCL_MEM_DEBUG must be either left defined for all modules or undefined
25 for all modules that are going to be linked together. If they are not,
26 link errors will occur, with either TclDbCkfree and Tcl_DbCkalloc or
27 Tcl_Ckalloc and Tcl_Ckfree being undefined.
28 Once memory debugging support has been compiled into Tcl, the C func‐
30 tions Tcl_ValidateAllMemory, and Tcl_DumpActiveMemory, and the Tcl mem‐
31 ory command can be used to validate and examine memory usage.
32
35 When memory debugging is enabled, whenever a call to ckalloc is made,
36 slightly more memory than requested is allocated so the memory debug‐
37 ging code can keep track of the allocated memory, and eight-byte
38 ``guard zones'' are placed in front of and behind the space that will
39 be returned to the caller. (The sizes of the guard zones are defined
40 by the C #define LOW_GUARD_SIZE and #define HIGH_GUARD_SIZE in the file
41 generic/tclCkalloc.c -- it can be extended if you suspect large over‐
42 write problems, at some cost in performance.) A known pattern is writ‐
43 ten into the guard zones and, on a call to ckfree, the guard zones of
44 the space being freed are checked to see if either zone has been modi‐
45 fied in any way. If one has been, the guard bytes and their new con‐
46 tents are identified, and a ``low guard failed'' or ``high guard
47 failed'' message is issued. The ``guard failed'' message includes the
48 address of the memory packet and the file name and line number of the
49 code that called ckfree. This allows you to detect the common sorts of
50 one-off problems, where not enough space was allocated to contain the
51 data written, for example.
52
55 Normally, Tcl compiled with memory debugging enabled will make it easy
56 to isolate a corruption problem. Turning on memory validation with the
57 memory command can help isolate difficult problems. If you suspect (or
58 know) that corruption is occurring before the Tcl interpreter comes up
59 far enough for you to issue commands, you can set MEM_VALIDATE define,
60 recompile tclCkalloc.c and rebuild Tcl. This will enable memory vali‐
61 dation from the first call to ckalloc, again, at a large performance
62 impact.
63 If you are desperate and validating memory on every call to ckalloc and
65 ckfree isn't enough, you can explicitly call Tcl_ValidateAllMemory
66 directly at any point. It takes a char * and an int which are normally
67 the filename and line number of the caller, but they can actually be
68 anything you want. Remember to remove the calls after you find the
69 problem.
70
73 ckalloc, memory, Tcl_ValidateAllMemory, Tcl_DumpActiveMemory
74
77 memory, debug
78Tcl 8.1 TCL_MEM_DEBUG(3)