Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
TCL_MEM_DEBUG(3)	    Tcl	Library	Procedures	      TCL_MEM_DEBUG(3)

______________________________________________________________________________

NAME
       TCL_MEM_DEBUG - Compile-time flag to enable Tcl memory debugging
______________________________________________________________________________

DESCRIPTION
       When Tcl	is compiled with TCL_MEM_DEBUG defined,	a powerful set of mem-
       ory debugging aids is included in the compiled binary.  This includes C
       and Tcl functions which can aid with debugging memory leaks, memory al-
       location	overruns, and other memory related errors.

ENABLING MEMORY	DEBUGGING
       To enable memory	debugging, Tcl should be recompiled from scratch  with
       TCL_MEM_DEBUG defined (e.g. by passing the --enable-symbols=mem flag to
       the configure script when building).  This will also compile in a  non-
       stub version of Tcl_InitMemory to add the memory	command	to Tcl.

       TCL_MEM_DEBUG  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 Tcl_DbCkfree and Tcl_DbCkalloc or
       Tcl_Alloc and Tcl_Free being undefined.

       Once memory debugging support has been compiled into Tcl, the  C	 func-
       tions Tcl_ValidateAllMemory, and	Tcl_DumpActiveMemory, and the Tcl mem-
       ory command can be used to validate and examine memory usage.

GUARD ZONES
       When memory debugging is	enabled, whenever a call to ckalloc  is	 made,
       slightly	 more  memory than requested is	allocated so the memory	debug-
       ging 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 re-
       turned to the caller.  (The sizes of the	guard zones are	defined	by the
       C  #define  LOW_GUARD_SIZE  and	#define	 HIGH_GUARD_SIZE  in  the file
       generic/tclCkalloc.c -- it can be extended if you suspect  large	 over-
       write problems, at some cost in performance.)  A	known pattern is writ-
       ten into	the guard zones	and, on	a call to ckfree, the guard  zones  of
       the  space being	freed are checked to see if either zone	has been modi-
       fied in any way.	 If one	has been, the guard bytes and their  new  con-
       tents  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 ckfree.  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.

DEBUGGING DIFFICULT MEMORY CORRUPTION PROBLEMS
       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 MEM_VALIDATE  define,
       recompile  tclCkalloc.c and rebuild Tcl.	 This will enable memory vali-
       dation from the first call to ckalloc, again, at	 a  large  performance
       impact.

       If you are desperate and	validating memory on every call	to ckalloc and
       ckfree is not enough, you can explicitly	call Tcl_ValidateAllMemory di-
       rectly  at  any point.  It takes	a char * and an	int 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.

SEE ALSO
       ckalloc,	memory,	Tcl_ValidateAllMemory, Tcl_DumpActiveMemory

KEYWORDS
       memory, debug

Tcl				      8.1		      TCL_MEM_DEBUG(3)

NAME | DESCRIPTION | ENABLING MEMORY DEBUGGING | GUARD ZONES | DEBUGGING DIFFICULT MEMORY CORRUPTION PROBLEMS | SEE ALSO | KEYWORDS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=TCL_MEM_DEBUG.tcl86&sektion=3&manpath=FreeBSD+12.2-RELEASE+and+Ports>

home | help