1 | '\" |
---|
2 | '\" Copyright (c) 1992-1999 Karl Lehenbauer and Mark Diekhans. |
---|
3 | '\" Copyright (c) 2000 by Scriptics Corporation. |
---|
4 | '\" All rights reserved. |
---|
5 | '\" |
---|
6 | '\" RCS: @(#) $Id: TCL_MEM_DEBUG.3,v 1.11 2007/12/13 15:22:32 dgp Exp $ |
---|
7 | '\" |
---|
8 | .so man.macros |
---|
9 | .TH TCL_MEM_DEBUG 3 8.1 Tcl "Tcl Library Procedures" |
---|
10 | .BS |
---|
11 | .SH NAME |
---|
12 | TCL_MEM_DEBUG \- Compile-time flag to enable Tcl memory debugging |
---|
13 | .BE |
---|
14 | .SH DESCRIPTION |
---|
15 | When Tcl is compiled with \fBTCL_MEM_DEBUG\fR defined, a powerful set |
---|
16 | of memory debugging aids is included in the compiled binary. This |
---|
17 | includes C and Tcl functions which can aid with debugging |
---|
18 | memory leaks, memory allocation overruns, and other memory related |
---|
19 | errors. |
---|
20 | .SH "ENABLING MEMORY DEBUGGING" |
---|
21 | .PP |
---|
22 | To enable memory debugging, Tcl should be recompiled from scratch with |
---|
23 | \fBTCL_MEM_DEBUG\fR defined (e.g. by passing the |
---|
24 | \fI\-\-enable\-symbols=mem\fR flag to the \fIconfigure\fR script when |
---|
25 | building). This will also compile in a non-stub |
---|
26 | version of \fBTcl_InitMemory\fR to add the \fBmemory\fR command to Tcl. |
---|
27 | .PP |
---|
28 | \fBTCL_MEM_DEBUG\fR must be either left defined for all modules or undefined |
---|
29 | for all modules that are going to be linked together. If they are not, link |
---|
30 | errors will occur, with either \fBTcl_DbCkfree\fR and \fBTcl_DbCkalloc\fR or |
---|
31 | \fBTcl_Ckalloc\fR and \fBTcl_Ckfree\fR being undefined. |
---|
32 | .PP |
---|
33 | Once memory debugging support has been compiled into Tcl, the C |
---|
34 | functions \fBTcl_ValidateAllMemory\fR, and \fBTcl_DumpActiveMemory\fR, |
---|
35 | and the Tcl \fBmemory\fR command can be used to validate and examine |
---|
36 | memory usage. |
---|
37 | .SH "GUARD ZONES" |
---|
38 | .PP |
---|
39 | When memory debugging is enabled, whenever a call to \fBckalloc\fR is |
---|
40 | made, slightly more memory than requested is allocated so the memory |
---|
41 | debugging code can keep track of the allocated memory, and eight-byte |
---|
42 | .QW "guard zones" |
---|
43 | are placed in front of and behind the space that will be |
---|
44 | returned to the caller. (The sizes of the guard zones are defined by the |
---|
45 | C #define \fBLOW_GUARD_SIZE\fR and #define \fBHIGH_GUARD_SIZE\fR |
---|
46 | in the file \fIgeneric/tclCkalloc.c\fR \(em it can |
---|
47 | be extended if you suspect large overwrite problems, at some cost in |
---|
48 | performance.) A known pattern is written into the guard zones and, on |
---|
49 | a call to \fBckfree\fR, the guard zones of the space being freed are |
---|
50 | checked to see if either zone has been modified in any way. If one |
---|
51 | has been, the guard bytes and their new contents are identified, and a |
---|
52 | .QW "low guard failed" |
---|
53 | or |
---|
54 | .QW "high guard failed" |
---|
55 | message is issued. The |
---|
56 | .QW "guard failed" |
---|
57 | message includes the address of the memory packet and |
---|
58 | the file name and line number of the code that called \fBckfree\fR. |
---|
59 | This allows you to detect the common sorts of one-off problems, where |
---|
60 | not enough space was allocated to contain the data written, for |
---|
61 | example. |
---|
62 | .SH "DEBUGGING DIFFICULT MEMORY CORRUPTION PROBLEMS" |
---|
63 | .PP |
---|
64 | Normally, Tcl compiled with memory debugging enabled will make it easy |
---|
65 | to isolate a corruption problem. Turning on memory validation with |
---|
66 | the memory command can help isolate difficult problems. If you |
---|
67 | suspect (or know) that corruption is occurring before the Tcl |
---|
68 | interpreter comes up far enough for you to issue commands, you can set |
---|
69 | \fBMEM_VALIDATE\fR define, recompile tclCkalloc.c and rebuild Tcl. |
---|
70 | This will enable memory validation from the first call to |
---|
71 | \fBckalloc\fR, again, at a large performance impact. |
---|
72 | .PP |
---|
73 | If you are desperate and validating memory on every call to |
---|
74 | \fBckalloc\fR and \fBckfree\fR is not enough, you can explicitly call |
---|
75 | \fBTcl_ValidateAllMemory\fR directly at any point. It takes a \fIchar |
---|
76 | *\fR and an \fIint\fR which are normally the filename and line number |
---|
77 | of the caller, but they can actually be anything you want. Remember |
---|
78 | to remove the calls after you find the problem. |
---|
79 | .SH "SEE ALSO" |
---|
80 | ckalloc, memory, Tcl_ValidateAllMemory, Tcl_DumpActiveMemory |
---|
81 | .SH KEYWORDS |
---|
82 | memory, debug |
---|