ckalloc,  memory,  ckfree, Tcl_DisplayMemory, Tcl_InitMem­
       ory, Tcl_ValidateAllMemory - 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_ValidateAllMemory.  File to display list of
       active memory.


DESCRIPTION

   ckalloc
       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

       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  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, spu­
       rious 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 abso­
       lutely 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  allo­
       cated  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  allo­
       cated  memory to the specified file.  The following infor­
       mation 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 use­
       ful 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

       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  com­
       pile  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 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   base­
       line/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  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.


THE MEMORY COMMAND

       memory options
              The Tcl memory command gives the Tcl developer con­
              trol 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.

              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 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  trac­
              ing  is  on, every call to ckalloc causes a line of
              trace information to be written to stderr, consist­
              ing  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 mem­
              ory  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
              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.

              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 corrup­
       tion 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 problem.


KEYWORDS

       ckalloc, ckfree, free, memory, malloc


Man(1) output converted with man2html