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