tcl/doc/memory.n

   1 '\"
   2 '\" Copyright (c) 1992-1999 by Karl Lehenbauer and Mark Diekhans
   3 '\" Copyright (c) 2000 by Scriptics Corporation.
   4 '\" All rights reserved.
   5 '\"
   6 '\" RCS: @(#) $Id$
   7 '\"
   8 .so man.macros
   9 .TH memory n 8.1 Tcl "Tcl Built-In Commands"
  10 .BS
  11 .SH NAME
  12 memory \- Control Tcl memory debugging capabilities.
  13 .SH SYNOPSIS
  14 \fBmemory \fIoption \fR?\fIarg arg ...\fR?
  15
  16 .SH DESCRIPTION
  17 .PP
  18 The \fBmemory\fR command gives the Tcl developer control of Tcl's memory
  19 debugging capabilities.  The memory command has several suboptions, which are
  20 described below.  It is only available when Tcl has been compiled with
  21 memory debugging enabled (when \fBTCL_MEM_DEBUG\fR is defined at
  22 compile time).
  23 .TP
  24 \fBmemory info\fR
  25 Produces a report containing the total allocations and frees since
  26 Tcl began, the current packets allocated (the current
  27 number of calls to \fBckalloc\fR not met by a corresponding call
  28 to \fBckfree\fR), the current bytes allocated, and the maximum number
  29 of packets and bytes allocated.
  30 .TP
  31 \fBmemory trace [on|off]\fR
  32 .br
  33 Turns memory tracing on or off.  When memory tracing is on, every call
  34 to \fBckalloc\fR causes a line of trace information to be written to
  35 \fIstderr\fR, consisting of the word \fIckalloc\fR, followed by the
  36 address returned, the amount of memory allocated, and the C filename
  37 and line number of the code performing the allocation.  For example:
  38 .CS
  39 ckalloc 40e478 98 tclProc.c 1406
  40 .CE
  41 Calls to \fBckfree\fR are traced in the same manner.
  42 .TP
  43 \fBmemory validate [on|off]\fR
  44 Turns memory validation on or off. When memory validation is enabled,
  45 on every call to \fBckalloc\fR or \fBckfree\fR, the guard zones are
  46 checked for every piece of memory currently in existence that was
  47 allocated by \fBckalloc\fR.  This has a large performance impact and
  48 should only be used when overwrite problems are strongly suspected.
  49 The advantage of enabling memory validation is that a guard zone
  50 overwrite can be detected on the first call to \fBckalloc\fR or
  51 \fBckfree\fR after the overwrite occurred, rather than when the
  52 specific memory with the overwritten guard zone(s) is freed, which may
  53 occur long after the overwrite occurred.
  54 .TP
  55 \fBmemory trace_on_at_malloc\fR \fIcount\fR
  56 Enable memory tracing after \fIcount\fR \fBckalloc\fR's have been performed.
  57 For example, if you enter \fBmemory trace_on_at_malloc 100\fR,
  58 after the 100th call to \fBckalloc\fR, memory trace information will begin
  59 being displayed for all allocations and frees.  Since there can be a lot
  60 of memory activity before a problem occurs, judicious use of this option
  61 can reduce the slowdown caused by tracing (and the amount of trace information
  62 produced), if you can identify a number of allocations that occur before
  63 the problem sets in.  The current number of memory allocations that have
  64 occurred since Tcl started is printed on a guard zone failure.
  65 .TP
  66 \fBmemory break_on_malloc\fR \fIcount\fR
  67 After the \fBcount\fR allocations have been performed, \fBckalloc\fR's
  68 output a message to this effect and that it is now attempting to enter
  69 the C debugger.  Tcl will then issue a \fISIGINT\fR signal against itself.
  70 If you are running Tcl under a C debugger, it should then enter the debugger
  71 command mode.
  72 .TP
  73 \fB memory display\fR \fIfile\fR
  74 Write a list of all currently allocated memory to the specified file.
  75
  76 .SH "SEE ALSO"
  77 ckalloc, ckfree, Tcl_ValidateAllMemory, Tcl_DumpActiveMemory, TCL_MEM_DEBUG
  78
  79 .SH KEYWORDS
  80 memory, debug
  81
  82