81 lines
3.6 KiB
Groff
81 lines
3.6 KiB
Groff
|
'\"
|
||
|
|
'\" Copyright (c) 1992-1999 Karl Lehenbauer & Mark Diekhans.
|
||
|
|
'\" Copyright (c) 2000 Scriptics Corporation.
|
||
|
|
'\" All rights reserved.
|
||
|
|
'\"
|
||
|
|
.TH TCL_MEM_DEBUG 3 8.1 Tcl "Tcl Library Procedures"
|
||
|
|
.so man.macros
|
||
|
|
.BS
|
||
|
|
.SH NAME
|
||
|
|
TCL_MEM_DEBUG \- Compile-time flag to enable Tcl memory debugging
|
||
|
|
.BE
|
||
|
|
.SH DESCRIPTION
|
||
|
|
When Tcl is compiled with \fBTCL_MEM_DEBUG\fR 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.
|
||
|
|
.SH "ENABLING MEMORY DEBUGGING"
|
||
|
|
.PP
|
||
|
|
To enable memory debugging, Tcl should be recompiled from scratch with
|
||
|
|
\fBTCL_MEM_DEBUG\fR defined (e.g. by passing the
|
||
|
|
\fI\-\-enable\-symbols=mem\fR flag to the \fIconfigure\fR script when
|
||
|
|
building). This will also compile in a non-stub
|
||
|
|
version of \fBTcl_InitMemory\fR to add the \fBmemory\fR command to Tcl.
|
||
|
|
.PP
|
||
|
|
\fBTCL_MEM_DEBUG\fR 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 \fBTcl_DbCkfree\fR and \fBTcl_DbCkalloc\fR or
|
||
|
|
\fBTcl_Alloc\fR and \fBTcl_Free\fR being undefined.
|
||
|
|
.PP
|
||
|
|
Once memory debugging support has been compiled into Tcl, the C
|
||
|
|
functions \fBTcl_ValidateAllMemory\fR, and \fBTcl_DumpActiveMemory\fR,
|
||
|
|
and the Tcl \fBmemory\fR command can be used to validate and examine
|
||
|
|
memory usage.
|
||
|
|
.SH "GUARD ZONES"
|
||
|
|
.PP
|
||
|
|
When memory debugging is enabled, whenever a call to \fBckalloc\fR is
|
||
|
|
made, slightly more memory than requested is allocated so the memory
|
||
|
|
debugging code can keep track of the allocated memory, and eight-byte
|
||
|
|
.QW "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 \fBLOW_GUARD_SIZE\fR and #define \fBHIGH_GUARD_SIZE\fR
|
||
|
|
in the file \fIgeneric/tclCkalloc.c\fR \(em 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 \fBckfree\fR, 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
|
||
|
|
.QW "low guard failed"
|
||
|
|
or
|
||
|
|
.QW "high guard failed"
|
||
|
|
message is issued. The
|
||
|
|
.QW "guard failed"
|
||
|
|
message includes the address of the memory packet and
|
||
|
|
the file name and line number of the code that called \fBckfree\fR.
|
||
|
|
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.
|
||
|
|
.SH "DEBUGGING DIFFICULT MEMORY CORRUPTION PROBLEMS"
|
||
|
|
.PP
|
||
|
|
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
|
||
|
|
\fBMEM_VALIDATE\fR define, recompile tclCkalloc.c and rebuild Tcl.
|
||
|
|
This will enable memory validation from the first call to
|
||
|
|
\fBckalloc\fR, again, at a large performance impact.
|
||
|
|
.PP
|
||
|
|
If you are desperate and validating memory on every call to
|
||
|
|
\fBckalloc\fR and \fBckfree\fR is not enough, you can explicitly call
|
||
|
|
\fBTcl_ValidateAllMemory\fR directly at any point. It takes a \fIchar
|
||
|
|
*\fR and an \fIint\fR 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.
|
||
|
|
.SH "SEE ALSO"
|
||
|
|
ckalloc, memory, Tcl_ValidateAllMemory, Tcl_DumpActiveMemory
|
||
|
|
.SH KEYWORDS
|
||
|
|
memory, debug
|