1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
|
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<!-- Created by texi2html 1.64 -->
<!--
Written by: Lionel Cons <Lionel.Cons@cern.ch> (original author)
Karl Berry <karl@freefriends.org>
Olaf Bachmann <obachman@mathematik.uni-kl.de>
and many others.
Maintained by: Olaf Bachmann <obachman@mathematik.uni-kl.de>
Send bugs and suggestions to <texi2html@mathematik.uni-kl.de>
-->
<HTML>
<HEAD>
<TITLE>Crystal Space: Memory Debugger Usage</TITLE>
<META NAME="description" CONTENT="Crystal Space: Memory Debugger Usage">
<META NAME="keywords" CONTENT="Crystal Space: Memory Debugger Usage">
<META NAME="resource-type" CONTENT="document">
<META NAME="distribution" CONTENT="global">
<META NAME="Generator" CONTENT="texi2html 1.64">
</HEAD>
<BODY LANG="" BGCOLOR="#FFFFFF" TEXT="#000000" LINK="#0000FF" VLINK="#800080" ALINK="#FF0000">
<A NAME="SEC634"></A>
<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="cs_267.html#SEC633"> < </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="cs_269.html#SEC635"> > </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="cs_263.html#SEC629"> << </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="cs_267.html#SEC633"> Up </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="cs_271.html#SEC637"> >> </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="index.html#SEC_Top">Top</A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="cs_toc.html#SEC_Contents">Contents</A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="cs_285.html#SEC711">Index</A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="cs_abt.html#SEC_About"> ? </A>]</TD>
</TR></TABLE>
<HR SIZE=1>
<H3> 8.4.1 Usage </H3>
<!--docid::SEC634::-->
<P>
To enable the memory debugger you should first of all compile in "debug"
mode. It is possible to use it in "optimize" mode but you will get
hexadecimal addresses instead of <EM>file name</EM>, <EM>function name</EM>, and
<EM>line number</EM> information.
</P><P>
Next, you don't need to recompile the engine from scratch, like you used to
do with the old memory debugger (that used <CODE>CHK()</CODE> macros). You just
work as usual and if you need the memory debugger, you recompile with the
`<SAMP>MEMDBG</SAMP>' variable set to 1. For example:
</P><P>
<TABLE><tr><td> </td><td class=example><pre>make walk mode=debug MEMDBG=1
</pre></td></tr></table></P><P>
This will just compile `<TT>memdbg.cpp</TT>' and link all other object files and
libraries with this one. Linking against this file automatically enables the
memory debugger.
</P><P>
Now you should create a map file for your executable. A map file is a text
file that contains information about source files, functions and line numbers
of your programs. The format of the map file is explained in the following
section. See section <A HREF="cs_269.html#SEC635">8.4.2 Map File Format</A>.
</P><P>
The map file is created with the `<TT>CS/bin/memdbg.sh</TT>' script. You do it
this way:
</P><P>
<TABLE><tr><td> </td><td class=example><pre>bin/memdbg.sh ./walktest [<VAR>options</VAR>]
</pre></td></tr></table></P><P>
This will create a file called `<TT>memdbg.map</TT>'. You also can provide some
options after giving the name of executable. These options tell the memory
debugger what tasks to perform. Here is a summary on each option. <EM>Note
that character case is significant!</EM>
</P><P>
<DL COMPACT>
<DT>`<SAMP>a</SAMP>'
<DD><EM>Fill memory after allocation with garbage.</EM> This is highly recommended
as it is not too expensive but allows to detect cases when memory is used
without being initialized first.
<P>
<DT>`<SAMP>f</SAMP>'
<DD><EM>Fill freed memory with garbage but don't actually free it.</EM>
<STRONG>Warning:</STRONG> This is quite expensive in terms of memory consumption.
<P>
<DT>`<SAMP>d</SAMP>'
<DD><EM>Cause program to brak into debugger upon detection of serious errors.</EM>
The debugger will break inside operator `<SAMP>new</SAMP>' or `<SAMP>delete</SAMP>' right
before exiting back to user program. By stepping a few times you can detect
the place where error occurred.
<P>
<DT>`<SAMP>v</SAMP>'
<DD><EM>Cause memory debugger to print an informational string each time
`<SAMP>new</SAMP>' or `<SAMP>delete</SAMP>' is called.</EM> It is recommended that you to
redirect `<SAMP>stdout</SAMP>' when using this flag as output to console will
immensely slow down your program.
<P>
<DT>`<SAMP>s</SAMP>'
<DD><EM>Emit a summary sheet at the end of program execution.</EM> The sheet will
list the summary number of memory allocations, deallocations, the peak memory
consumption, and a lot of other useful information.
<P>
<DT>`<SAMP>l</SAMP>'
<DD><EM>Emit a list of unfreed memory blocks at the end of program.</EM> The list
will also contain the location where the corresponding memory block was
allocated.
<P>
<DT>`<SAMP>b</SAMP>'
<DD><EM>Detect writes past the block boundaries.</EM> This is implemented by
allocating slightly bigger blocks than actually requested, and by filling
those inter-block spaces with some well-known value. When block is freed, the
space between blocks is checked to verify that it still contains the same
well-known value.
<P>
<DT>`<SAMP>L</SAMP>'
<DD><EM>Redirect (append) output from console to a log file called
`<TT>memdbg.log</TT>'.</EM>
</DL>
<P>
Default options are `<SAMP>aslbL</SAMP>'. To enable extensive checking use
`<SAMP>aslbLf</SAMP>'. To enable all options use `<SAMP>aslbLfdv</SAMP>'. Thus, to disable
everything except the log file and the summary, you type:
</P><P>
<TABLE><tr><td> </td><td class=example><pre>bin/memdbg.sh ./walktest sL
</pre></td></tr></table></P><P>
After you created the map file, just run your program as usual. If your
program doesn't have a separate `<SAMP>stdout</SAMP>' stream (such as on DOS,
OS/2, Windows, MacOS/9) it is recommended that you always use log file;
if you didn't you can still redirect the `<SAMP>stdout</SAMP>' to a file using the
`<SAMP>stdout</SAMP>' redirection, if it is possible (for intance, `<SAMP>./walktest >
logfile</SAMP>').
</P><P>
If you will want later to change debugging options, you can load the map file
into any text editor (that will handle such large files) and change the first
line (that starts with a capital `<SAMP>O</SAMP>').
</P><P>
If you did everything correctly, you should get similar references to
locations:
</P><P>
<TABLE><tr><td> </td><td class=example><pre>+--------+----------+- Unfreed memory blocks -------------------
| size | address |location where block was allocated
+--------+----------+-------------------------------------------
| 239| 0x89970|file /home/CS/memdbg/test.cpp:28, func main
</pre></td></tr></table></P><P>
If you get such text:
</P><P>
<TABLE><tr><td> </td><td class=example><pre>+--------+----------+- Unfreed memory blocks--------------------
| size | address |location where block was allocated
+--------+----------+-------------------------------------------
| 200| 0x32b70|unknown (0x10239)
| 239| 0x87f50|unknown (0x10189)
</pre></td></tr></table></P><P>
This means that the map file is either incorrect, or does not contain location
information about the above addresses. However, this does not invalidate the
usefulness of the memory debugger, it just makes reading of the log file more
complex. Usually each compiler system provides a way to find out the source
module and the line number that is closest to given address. For GNU set
of development tools this is done with the `<TT>addr2line</TT>' tool. You also
can do it with `<TT>gdb</TT>'.
</P><P>
<A NAME="Memory Debugger mapfile"></A>
<HR SIZE=1>
<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="cs_267.html#SEC633"> < </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="cs_269.html#SEC635"> > </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="cs_263.html#SEC629"> << </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="cs_267.html#SEC633"> Up </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="cs_271.html#SEC637"> >> </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="index.html#SEC_Top">Top</A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="cs_toc.html#SEC_Contents">Contents</A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="cs_285.html#SEC711">Index</A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="cs_abt.html#SEC_About"> ? </A>]</TD>
</TR></TABLE>
<BR>
<FONT SIZE="-1">
This document was generated
using <A HREF="http://www.mathematik.uni-kl.de/~obachman/Texi2html
"><I>texi2html</I></A>
</BODY>
</HTML>
|
