1 files changed, 81 insertions, 0 deletions
diff --git a/doc/TCL_MEM_DEBUG.3 b/doc/TCL_MEM_DEBUG.3
new file mode 100644
index 0000000..bf6e2fe
--- /dev/null
+++ b/doc/TCL_MEM_DEBUG.3
@@ -0,0 +1,81 @@
+'\" 
+'\" Copyright (c) 1992-1999 Karl Lehenbauer and Mark Diekhans.
+'\" Copyright (c) 2000 by Scriptics Corporation.
+'\" All rights reserved.
+'\" 
+'\" RCS: @(#) $Id: TCL_MEM_DEBUG.3,v 1.1 2000/04/27 01:46:59 ericm Exp $
+'\" 
+.so man.macros
+.TH TCL_MEM_DEBUG 3 8.1 Tcl "Tcl Library Procedures"
+.BS
+.SH NAME
+TCL_MEM_DEBUG \- Compile-time flag to enable Tcl memory debugging.
+
+.SH DESCRIPTION
+When Tcl is compiled with \fBTCL_MEM_DEBUG\fR defined, a powerful set
+of memory debugging aids are 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.  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 \fBTclDbCkfree\fR and \fBTcl_DbCkalloc\fR or
+\fBTcl_Ckalloc\fR and \fBTcl_Ckfree\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 ``guard
+zones'' are placed in front of and behind the space that will be
+returned to the caller.  (The size of the guard zone is defined by the
+C #define \fBGUARD_SIZE\fR in \fIbaseline/src/ckalloc.c\fR -- 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
+``low guard failed'' or ``high guard failed'' message is issued.  The
+``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 isn't 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
+memory, Tcl_ValidateAllMemory, Tcl_DumpActiveMemory
+
+.SH KEYWORDS
+memory, debug
+
+