tcl/doc/DumpActiveMemory.3

   1 '\"
   2 '\" Copyright (c) 1992-1999 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 "Tcl_DumpActiveMemory" 3 8.1 Tcl "Tcl Library Procedures"
  10 .BS
  11 .SH NAME
  12 Tcl_DumpActiveMemory, Tcl_InitMemory, Tcl_ValidateAllMemory \- Validated memory allocation interface.
  13 .SH SYNOPSIS
  14 .nf
  15 \fB#include <tcl.h>\fR
  16 .sp
  17 int
  18 \fBTcl_DumpActiveMemory\fR(\fIfileName\fR)
  19 .sp
  20 void
  21 \fBTcl_InitMemory\fR(\fIinterp\fR)
  22 .sp
  23 void
  24 \fBTcl_ValidateAllMemory\fR(\fIfileName, line\fR)
  25
  26 .SH ARGUMENTS
  27 .AP Tcl_Interp *interp in
  28 Tcl interpreter in which to add commands.
  29 .AP "CONST char" *fileName in
  30 For \fBTcl_DumpActiveMemory\fR, name of the file to which memory
  31 information will be written.  For \fBTcl_ValidateAllMemory\fR, name of
  32 the file from which the call is being made (normally \fB__FILE__\fR).
  33 .AP int line in
  34 Line number at which the call to \fBTcl_ValidateAllMemory\fR is made
  35 (normally \fB__LINE__\fR).
  36 .BE
  37
  38 .SH DESCRIPTION
  39 These functions provide access to Tcl memory debugging information.
  40 They are only functional when Tcl has been compiled with
  41 \fBTCL_MEM_DEBUG\fR defined at compile-time.  When \fBTCL_MEM_DEBUG\fR
  42 is not defined, these functions are all no-ops.
  43 .PP
  44 \fBTcl_DumpActiveMemory\fR will output a list of all currently
  45 allocated memory to the specified file.  The information output for
  46 each allocated block of memory is:  starting and ending addresses
  47 (excluding guard zone), size, source file where \fBckalloc\fR was
  48 called to allocate the block and line number in that file.  It is
  49 especially useful to call \fBTcl_DumpActiveMemory\fR after the Tcl
  50 interpreter has been deleted.
  51 .PP
  52 \fBTcl_InitMemory\fR adds the Tcl \fBmemory\fR command to the
  53 interpreter given by \fIinterp\fR.  \fBTcl_InitMemory\fR is called
  54 by \fBTcl_Main\fR.
  55 .PP
  56 \fBTcl_ValidateAllMemory\fR forces a validation of the guard zones of
  57 all currently allocated blocks of memory.  Normally validation of a
  58 block occurs when its freed, unless full validation is enabled, in
  59 which case validation of all blocks occurs when \fBckalloc\fR and
  60 \fBckfree\fR are called.  This function forces the validation to occur
  61 at any point.
  62
  63 .SH "SEE ALSO"
  64 TCL_MEM_DEBUG, memory
  65
  66 .SH KEYWORDS
  67 memory, debug
  68
  69