Unix/Linux Go Back    

RedHat 9 (Linux i386) - man page for memory (redhat section n)

Linux & Unix Commands - Search Man Pages
Man Page or Keyword Search:   man
Select Man Page Set:       apropos Keyword Search (sections above)

Memory(TCL)									      Memory(TCL)

       ckalloc,  memory, ckfree, Tcl_DisplayMemory, Tcl_InitMemory, Tcl_ValidateAllMemory - Vali-
       dated memory allocation interface.

       memory info

       memory trace [on|off]

       memory validate [on|off]

       memory trace_on_at_malloc nnn

       memory break_on_malloc nnn

       memory display file

       #include <tcl.h>

       char *
       ckalloc (unsigned size)

       ckfree (char *ptr)

       Tcl_DumpActiveMemory (char *fileName);

       Tcl_ValidateAllMemory (char *file,
			      int   line)

       Tcl_InitMemory (interp)

       A pointer to the Tcl interpreter.  The filename of the  caller  of  Tcl_ValidateAllMemory.
       The  line  number  of the caller of Tcl_ValidateAllMemory.  File to display list of active

       Thi macro allocates memory, in the same manner as malloc, with the following  differences:
       One, ckalloc checks the value returned from malloc (it calls malloc for you) and panics if
       the allocation request fails.  Two, if enabled at compile time, a version of ckalloc  with
       special	memory	debugging capabilities replaces the normal version of ckalloc, which aids
       in detecting memory overwrites and leaks (repeated allocations not matched by  correspond-
       ing frees).

	 o size - The size of the memory block to be allocated.

	 A pointer to the allocated memory block.

       This  macro  frees  memory  allocated  by ckalloc.  Like ckalloc, when memory debugging is
       enabled, ckfree has enhanced capabilities for detecting memory overwrites and leaks.

       It is very important that you use ckalloc when you need to allocate memory, and	that  you
       use  ckfree  to	free  it.  Should you use malloc to allocate and ckfree to free, spurious
       memory validation errors will occur when memory debugging is enabled.  Should you use free
       to free memory allocated by ckalloc, memory corruption will occur when memory debugging is
       enabled.  Any memory that is to be become the property of the  Tcl  interpreter,  such  as
       result space, must be allocated with ckalloc.  If it is absolutely necessary for an appli-
       cation to pass back malloced memory to Tcl, it will work only if Tcl is complied with  the
       TCL_MEM_DEBUG  flag  turned off.  If you convert your application to use this facility, it
       will help you find memory over runs and lost memory.  Note that memory allocated  by  a	C
       library	routine  requiring freeing should still be freed with free, since it calls malloc
       rather than ckalloc to do the allocation.

	 o ptr - The address of a block to free, as returned by ckalloc.

       This function will output a list of all currently allocated memory to the specified  file.
       The  following  information  is outputted for each allocated block of memory: starting and
       ending addresses (excluding guard zone), size, source file where  ckalloc  was  called  to
       allocate  the  block  and  line	number	in  that  file.   It is especially useful to call
       Tcl_DumpActiveMemory after the Tcl interpreter has been deleted.

	 o fileName - The name of the file to output the memory list to.

       Forces a validation of the guard zones of all currently allocated blocks of memory.   Nor-
       mally  validation  of a block occurs when its freed, unless full validation is enabled, in
       which case validation of all blocks occurs when ckalloc and ckfree are called.  This func-
       tion forces the validation to occur at any point.

	 o file - The file that this routine is being called from, normally __FILE__.
	 o line - The line that this routine is being called from, normally __LINE__.

       To  enable  memory  debugging,  Tcl  should  be recompiled from scratch with TCL_MEM_DEBUG
       defined.  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 TclDbCkfree and Tcl_DbCkalloc or Tcl_Ckalloc and Tcl_Ckfree being undefined.

       When memory debugging is enabled, whenever a call to ckalloc is made, slightly more memory
       than requested is allocated so the memory debugging code can keep track of  the	allocated
       memory,	and  also  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	GUARD_SIZE  in	baseline/src/ckalloc.c -- 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 ckfree, 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 ckfree.  This allows you to
       detect the common sorts of one-off problems, where not enough space was allocated to  con-
       tain the data written, for example.

       memory options
	      The  Tcl	memory	command gives the Tcl developer control of Tcl's memory debugging
	      capabilities.  The memory command  has  several  suboptions,  which  are	described
	      below.   It  is  only  available	when  Tcl has been compiled with memory debugging

       memory info
	      Produces a report containing the total allocations and frees since Tcl  began,  the
	      current packets allocated (the current number of calls to ckalloc not met by a cor-
	      responding call to ckfree), the current bytes allocated, and the maximum number  of
	      packets and bytes allocated.

       memory trace [on|off]
	      Turns  memory  tracing on or off.  When memory tracing is on, every call to ckalloc
	      causes a line of trace information to be written to stderr, consisting of the  word
	      ckalloc,	followed by the address returned, the amount of memory allocated, and the
	      C filename and line number of the code performing the allocation, for example...

		 ckalloc 40e478 98 tclProc.c 1406

	      Calls to ckfree are traced in the same manner, except  that  the	word  ckalloc  is
	      replaced by the word ckfree.

       memory validate [on|off]
	      Turns  memory  validation  on  or off.  When memory validation is enabled, on every
	      call to ckalloc or ckfree, the guard zones are checked for every	piece  of  memory
	      currently in existence that was allocated by ckalloc.  This has a large performance
	      impact and should only be used when overwrite problems are strongly suspected.  The
	      advantage  of  enabling  memory  validation  is  that a guard zone overwrite can be
	      detected on the first call to ckalloc  or  ckfree  after	the  overwrite	occurred,
	      rather  than  when the specific memory with the overwritten guard zone(s) is freed,
	      which may occur long after the overwrite occurred.

       memory trace_on_at_malloc nnn
	      Enable memory tracing after nnn ckallocs have been performed.  For example, if  you
	      enter  memory trace_on_at_malloc 100, after the 100th call to ckalloc, memory trace
	      information will begin being displayed for all allocations and frees.  Since  there
	      can  be  a  lot  of  memory activity before a problem occurs, judicious use of this
	      option can reduce the slowdown caused by tracing (and the amount of trace  informa-
	      tion  produced),	if you can identify a number of allocations that occur before the
	      problem sets in.	The current number of memory allocations that have occurred since
	      Tcl started is printed on a guard zone failure.

       memory break_on_malloc nnn
	      After  the  nnn  allocations have been performed, ckallocs output a message to this
	      effect and that it is now attempting to enter the C debugger.  Tcl will then  issue
	      a  SIGINT  signal  against  itself.   If you are running Tcl under a C debugger, it
	      should then enter the debugger command mode.

       memory display file
	      Write a list of all currently allocated memory to the specified file.

       Normally, Tcl compiled with memory debugging enabled will make it easy to isolate  a  cor-
       ruption	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  validation  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 isn't
       enough, you can explicitly call Tcl_ValidateAllMemory directly 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  prob-

       ckalloc, ckfree, free, memory, malloc

Tcl										      Memory(TCL)
Unix & Linux Commands & Man Pages : ©2000 - 2018 Unix and Linux Forums

All times are GMT -4. The time now is 12:38 AM.