ABCDEFGHIJKLMNOPQRSTUVWXYZ

Tcl_DisplayMemory

Memory(TCL)                                                        Memory(TCL)



NAME
       ckalloc,  memory,  ckfree, Tcl_DisplayMemory, Tcl_InitMemory, Tcl_Vali-
       dateAllMemory - Validated memory allocation interface.

SYNOPSIS
       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)

       void
       ckfree (char *ptr)

       int
       Tcl_DumpActiveMemory (char *fileName);

       void
       Tcl_ValidateAllMemory (char *file,
                              int   line)

       void
       Tcl_InitMemory (interp)

ARGUMENTS
       A pointer to the Tcl  interpreter.   The  filename  of  the  caller  of
       Tcl_ValidateAllMemory.   The  line  number  of  the caller of Tcl_Vali-
       dateAllMemory.  File to display list of active memory.


DESCRIPTION
   ckalloc
       Thi macro allocates memory, in the same manner as malloc, with the fol-
       lowing  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 mem-
       ory debugging capabilities replaces  the  normal  version  of  ckalloc,
       which  aids  in detecting memory overwrites and leaks (repeated alloca-
       tions not matched by corresponding frees).

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

       Returns:
         A pointer to the allocated memory block.

   ckfree
       This macro frees memory allocated by ckalloc.  Like ckalloc, when  mem-
       ory   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 application 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.

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


   Tcl_DumpActiveMemory
       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.

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

   Tcl_ValidateAllMemory
       Forces a validation of the  guard  zones  of  all  currently  allocated
       blocks  of  memory.   Normally  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 function
       forces the validation to occur at any point.

       Parameters:
         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__.

ENABLING MEMORY DEBUGGING
       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.

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 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 per-
       formance.)  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 contain the data written, for example.

THE MEMORY COMMAND
       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 enabled.

       memory info
              Produces  a  report  containing  the total allocations and frees
              since Tcl began, the current packets allocated (the current num-
              ber  of  calls  to  ckalloc  not  met by a corresponding 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 information produced), if you can iden-
              tify  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.

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 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
       problem.

KEYWORDS
       ckalloc, ckfree, free, memory, malloc





Tcl                                                                Memory(TCL)