[25] | 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: memory.n,v 1.12 2008/01/18 15:51:08 dkf Exp $ |
---|
| 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 | .BE |
---|
| 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), and after \fBTcl_InitMemory\fR has been called. |
---|
| 23 | .TP |
---|
| 24 | \fBmemory active\fR \fIfile\fR |
---|
| 25 | . |
---|
| 26 | Write a list of all currently allocated memory to the specified \fIfile\fR. |
---|
| 27 | .TP |
---|
| 28 | \fBmemory break_on_malloc\fR \fIcount\fR |
---|
| 29 | . |
---|
| 30 | After the \fIcount\fR allocations have been performed, \fBckalloc\fR |
---|
| 31 | outputs a message to this effect and that it is now attempting to enter |
---|
| 32 | the C debugger. Tcl will then issue a \fISIGINT\fR signal against itself. |
---|
| 33 | If you are running Tcl under a C debugger, it should then enter the debugger |
---|
| 34 | command mode. |
---|
| 35 | .TP |
---|
| 36 | \fBmemory info\fR |
---|
| 37 | . |
---|
| 38 | Returns a report containing the total allocations and frees since |
---|
| 39 | Tcl began, the current packets allocated (the current |
---|
| 40 | number of calls to \fBckalloc\fR not met by a corresponding call |
---|
| 41 | to \fBckfree\fR), the current bytes allocated, and the maximum number |
---|
| 42 | of packets and bytes allocated. |
---|
| 43 | .TP |
---|
| 44 | \fB memory init \fR[\fBon\fR|\fBoff\fR] |
---|
| 45 | . |
---|
| 46 | Turn on or off the pre-initialization of all allocated memory |
---|
| 47 | with bogus bytes. Useful for detecting the use of uninitialized values. |
---|
| 48 | .TP |
---|
| 49 | \fBmemory onexit\fR \fIfile\fR |
---|
| 50 | . |
---|
| 51 | Causes a list of all allocated memory to be written to the specified \fIfile\fR |
---|
| 52 | during the finalization of Tcl's memory subsystem. Useful for checking |
---|
| 53 | that memory is properly cleaned up during process exit. |
---|
| 54 | .TP |
---|
| 55 | \fBmemory tag\fR \fIstring\fR |
---|
| 56 | . |
---|
| 57 | Each packet of memory allocated by \fBckalloc\fR can have associated |
---|
| 58 | with it a string-valued tag. In the lists of allocated memory generated |
---|
| 59 | by \fBmemory active\fR and \fBmemory onexit\fR, the tag for each packet |
---|
| 60 | is printed along with other information about the packet. The |
---|
| 61 | \fBmemory tag\fR command sets the tag value for subsequent calls |
---|
| 62 | to \fBckalloc\fR to be \fIstring\fR. |
---|
| 63 | .TP |
---|
| 64 | \fBmemory trace \fR[\fBon\fR|\fBoff\fR] |
---|
| 65 | . |
---|
| 66 | Turns memory tracing on or off. When memory tracing is on, every call |
---|
| 67 | to \fBckalloc\fR causes a line of trace information to be written to |
---|
| 68 | \fIstderr\fR, consisting of the word \fIckalloc\fR, followed by the |
---|
| 69 | address returned, the amount of memory allocated, and the C filename |
---|
| 70 | and line number of the code performing the allocation. For example: |
---|
| 71 | .RS |
---|
| 72 | .CS |
---|
| 73 | ckalloc 40e478 98 tclProc.c 1406 |
---|
| 74 | .CE |
---|
| 75 | Calls to \fBckfree\fR are traced in the same manner. |
---|
| 76 | .RE |
---|
| 77 | .TP |
---|
| 78 | \fBmemory trace_on_at_malloc\fR \fIcount\fR |
---|
| 79 | . |
---|
| 80 | Enable memory tracing after \fIcount\fR \fBckalloc\fRs have been performed. |
---|
| 81 | For example, if you enter \fBmemory trace_on_at_malloc 100\fR, |
---|
| 82 | after the 100th call to \fBckalloc\fR, memory trace information will begin |
---|
| 83 | being displayed for all allocations and frees. Since there can be a lot |
---|
| 84 | of memory activity before a problem occurs, judicious use of this option |
---|
| 85 | can reduce the slowdown caused by tracing (and the amount of trace information |
---|
| 86 | produced), if you can identify a number of allocations that occur before |
---|
| 87 | the problem sets in. The current number of memory allocations that have |
---|
| 88 | occurred since Tcl started is printed on a guard zone failure. |
---|
| 89 | .TP |
---|
| 90 | \fBmemory validate \fR[\fBon\fR|\fBoff\fR] |
---|
| 91 | . |
---|
| 92 | Turns memory validation on or off. When memory validation is enabled, |
---|
| 93 | on every call to \fBckalloc\fR or \fBckfree\fR, the guard zones are |
---|
| 94 | checked for every piece of memory currently in existence that was |
---|
| 95 | allocated by \fBckalloc\fR. This has a large performance impact and |
---|
| 96 | should only be used when overwrite problems are strongly suspected. |
---|
| 97 | The advantage of enabling memory validation is that a guard zone |
---|
| 98 | overwrite can be detected on the first call to \fBckalloc\fR or |
---|
| 99 | \fBckfree\fR after the overwrite occurred, rather than when the |
---|
| 100 | specific memory with the overwritten guard zone(s) is freed, which may |
---|
| 101 | occur long after the overwrite occurred. |
---|
| 102 | .SH "SEE ALSO" |
---|
| 103 | ckalloc, ckfree, Tcl_ValidateAllMemory, Tcl_DumpActiveMemory, TCL_MEM_DEBUG |
---|
| 104 | .SH KEYWORDS |
---|
| 105 | memory, debug |
---|