diff options
Diffstat (limited to 'tcl8.6/doc/TCL_MEM_DEBUG.3')
-rw-r--r-- | tcl8.6/doc/TCL_MEM_DEBUG.3 | 80 |
1 files changed, 80 insertions, 0 deletions
diff --git a/tcl8.6/doc/TCL_MEM_DEBUG.3 b/tcl8.6/doc/TCL_MEM_DEBUG.3 new file mode 100644 index 0000000..e3a6809 --- /dev/null +++ b/tcl8.6/doc/TCL_MEM_DEBUG.3 @@ -0,0 +1,80 @@ +'\" +'\" Copyright (c) 1992-1999 Karl Lehenbauer and Mark Diekhans. +'\" Copyright (c) 2000 by 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 |