/usr/gnu/man/cat.n/memory.n.Z(/usr/gnu/man/cat.n/memory.n.Z)

______________________________________________________________________________

NAME

       memory - Control Tcl memory debugging capabilities.

SYNOPSIS

       memory option ?arg arg ...?
_________________________________________________________________

DESCRIPTION

       The  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 com-
       piled with memory debugging enabled (when TCL_MEM_DEBUG is  defined  at
       compile time), and after Tcl_InitMemory has been called.

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

       memory break_on_malloc count
              After the count allocations have been performed, ckalloc outputs
              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 info
              Returns 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 init [on|off]
              Turn on or off the pre-initialization of  all  allocated  memory
              with bogus bytes.  Useful for detecting the use of uninitialized
              values.

       memory onexit file
              Causes a list of all allocated memory to be written to the spec-
              ified  file  during  the finalization of Tcl's memory subsystem.
              Useful for checking that memory is properly  cleaned  up  during
              process exit.

       memory tag string
              Each  packet  of memory allocated by ckalloc can have associated
              with it a string-valued tag.  In the lists of  allocated  memory
              generated  by  memory active and memory onexit, the tag for each
              packet is printed along with other information about the packet.
              The  memory  tag command sets the tag value for subsequent calls
              to ckalloc to be string.

       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.

       memory trace_on_at_malloc count
              Enable memory tracing after count ckalloc's 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 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.

SEE ALSO

       ckalloc,     ckfree,    Tcl_ValidateAllMemory,    Tcl_DumpActiveMemory,
       TCL_MEM_DEBUG

KEYWORDS

       memory, debug

Tcl                                   8.1                            memory(n)