| 1 |
<h3>Table of contents</h3> <UL> |
| 2 |
<LI><a href="#chap0">Introduction</a> |
| 3 |
<LI><a href="#chap1">Requirements</a> |
| 4 |
<LI><a href="#chap2">Installation</a> |
| 5 |
<LI><a href="#chap3">Running with LeakTracer</a> |
| 6 |
<LI><a href="#chap4">Detectable errors</a> |
| 7 |
<LI><a href="#chap5">Analyzing output</a> |
| 8 |
<LI><a href="#chap6">Shared libraries and objects</a> |
| 9 |
<LI><a href="#chap7">Licensing</a> |
| 10 |
<LI><a href="#chap8">Credits</a> |
| 11 |
<LI><a href="#chap9">Revision history</a> |
| 12 |
</UL> |
| 13 |
<PRE> |
| 14 |
</PRE><h3><a name="chap0">Introduction</a></h3><PRE> |
| 15 |
LeakTracer is a small tool I wrote when checking a C++ program for memory |
| 16 |
leaks. I couldn't get dmalloc to display what I wanted, and I just saw the |
| 17 |
__builtin_return_address gcc-extension mentioned. |
| 18 |
|
| 19 |
To use LeakTracer, run your program using the provided LeakCheck script. It |
| 20 |
uses the LD_PRELOAD feature to "overlay" some functions on top of your |
| 21 |
functions (no recompile needed). If your platform does not support LD_PRELOAD, |
| 22 |
you can add the LeakTracer.o object file to the objects in your Makefile and |
| 23 |
run your application. |
| 24 |
|
| 25 |
LeakTracer uses gdb to print out the exact line where the memory was allocated |
| 26 |
and not freed - this of course means you have to free all dynamically |
| 27 |
allocated data. LeakTracer also overrides the global operator new and operator |
| 28 |
delete - this will give problems if you override them as well. |
| 29 |
|
| 30 |
LeakTracer traces only new/new[] and delete calls - it does not look at |
| 31 |
malloc/free/realloc. |
| 32 |
|
| 33 |
Here is some example output: |
| 34 |
|
| 35 |
Gathered 8 (8 unique) points of data. |
| 36 |
(gdb) |
| 37 |
Allocations: 1 / Size: 36 |
| 38 |
0x80608e6 is in NullArcableInstance::NullArcableInstance(void) (Machine.cc:40). |
| 39 |
39 public: |
| 40 |
40 NullArcableInstance() : ArcableInstance(new NullArcable) {} |
| 41 |
|
| 42 |
Allocations: 1 / Size: 8 |
| 43 |
0x8055b02 is in init_types(void) (Type.cc:119). |
| 44 |
118 void init_types() { |
| 45 |
119 Type::Integer = new IntegerType; |
| 46 |
|
| 47 |
Allocations: 1 / Size: 132 (new[]) |
| 48 |
0x805f4ab is in Hashtable<NativeCallable, String, false, true>::Hashtable(unsigned int) (ea/h/Hashtable.h:15). |
| 49 |
14 Hashtable (uint _size = 32) : size(_size), count(0) { |
| 50 |
15 table = new List<E, own> [size]; |
| 51 |
|
| 52 |
[...] |
| 53 |
|
| 54 |
</PRE><h3><a name="chap1">Requirements</a></h3><PRE> |
| 55 |
You need Perl5 and gdb installed to run the leak-analyzer. You need gcc -- I |
| 56 |
currently use 2.95 but have used it with previous older versions without |
| 57 |
problems. |
| 58 |
You also need to run this on an architecture which supports |
| 59 |
__builtin_return_address arguments that are greater than 0 - there may be |
| 60 |
some problems on MIPS there. |
| 61 |
|
| 62 |
So far this code has been tested under Linux 2.2, x86 system, Solaris and |
| 63 |
HP-UX. |
| 64 |
</PRE><h3><a name="chap2">Installation</a></h3><PRE> |
| 65 |
Just type make. There is no install target; you should put LeakTracer |
| 66 |
some place you can remember. |
| 67 |
|
| 68 |
Since version 2.0, it is possible to preload the LeakTracer object on |
| 69 |
architectures that support LD_PRELOAD (this is at least Linux and probably |
| 70 |
others -- please report success/failure). This means it is much easier to use |
| 71 |
the program: you do not need to relink your program with LeakTracer.o. |
| 72 |
|
| 73 |
In case your platform does not support LD_PRELOAD, you can use LeakTracer in |
| 74 |
the old pre 2.0 way: add LeakTracer.o to your object files -- at the very end |
| 75 |
of them (also after -llibrary lines). |
| 76 |
|
| 77 |
In any case your application must also be compiled with debugging enabled |
| 78 |
(i.e. -g). |
| 79 |
|
| 80 |
</PRE><h3><a name="chap3">Running with LeakTracer</a></h3><PRE> |
| 81 |
If you are using the shared object, run the LeakCheck script. This script |
| 82 |
should stay in the directory where you install LeakCheck -- it will search for |
| 83 |
LeakTracer.so file there and load it. E.g.: |
| 84 |
|
| 85 |
~/src/LeakTracer/LeakCheck yourApplication |
| 86 |
|
| 87 |
(if you put LeakTracer in ~/src/LeakTracer/) |
| 88 |
|
| 89 |
Run your application as normal, performing tasks that you want to be traced |
| 90 |
for memory leaks. While the application runs, LeakTracer will write data about |
| 91 |
memory allocation to the file "leak.out" in the current directory. You can |
| 92 |
override the location of that file by setting the LEAKTRACE_FILE environment |
| 93 |
variable. |
| 94 |
|
| 95 |
If you cannot use LD_PRELOAD, just run your application as normal after |
| 96 |
relinking it. It will also produce a "leak.out" file when it finishes. |
| 97 |
</PRE><h3><a name="chap4">Detectable errors</a></h3><PRE> |
| 98 |
LeakTracer is capable to detect the following problems with your program |
| 99 |
|
| 100 |
1) memory which is allocated but not freed |
| 101 |
2) (limited support for) overwritten memory at the end of the allocated |
| 102 |
block ( reason = 1 ) |
| 103 |
3) memory which is tried to be deleted but which is not allocated |
| 104 |
(either because of a garbage pointer or twice deletion) |
| 105 |
(reason = 2) |
| 106 |
4) memory which is allocated with new[] but deleted with simple delete |
| 107 |
and vice versa (reason = 4) |
| 108 |
|
| 109 |
For the last three problems, LeakTracer can abort() your program if you |
| 110 |
tell it so; the resulting core-dump allows to debug the problem. By default, |
| 111 |
only the overwrite memory condition results in an abort of the program |
| 112 |
because it is inherently critical. The two other conditions are not critical. |
| 113 |
You can influence what LeakTracer does with the environment variable |
| 114 |
LT_ABORTREASON |
| 115 |
which you can set to some numeric value which is the result of the |
| 116 |
sum of the reasons you find in the parentesis in the enumeration above. |
| 117 |
To abort on any reason, for example, you would set LT_ABORTREASON to 7. |
| 118 |
</PRE><h3><a name="chap5">Analyzing output</a></h3><PRE> |
| 119 |
You should then run leak-analyze, since looking at the raw leak.out file will |
| 120 |
not help you much. To run leak-analyze, you need Perl as well as gdb |
| 121 |
installed (any version of gdb will do). For example: |
| 122 |
|
| 123 |
leak-analyze myprog leak.out |
| 124 |
|
| 125 |
You don't have to specify the leak.out filename if you just use the default |
| 126 |
one. leak-analyze will run gdb on the file, sending it a number of commands |
| 127 |
that will show the source lines with the memory leaks. |
| 128 |
|
| 129 |
leak-analyze should show you something like this: |
| 130 |
|
| 131 |
Gathered 2 (2 unique) points of data. |
| 132 |
|
| 133 |
#-- Alloc: Different allocation schemes |
| 134 |
alloc here :0x80485b7 is in main (test.cc:6). |
| 135 |
5 |
| 136 |
6 int *wrong = new int[10]; |
| 137 |
..free here :0x80485d9 is in main (test.cc:11). |
| 138 |
11 delete wrong; |
| 139 |
|
| 140 |
#-- Leak: Allocations: 1 / Size: 168 |
| 141 |
0x8048593 is in main (test.cc:3). |
| 142 |
2 int main() { |
| 143 |
3 int *array = new int [42] ; |
| 144 |
|
| 145 |
#-- Leak: Allocations: 1 / Size: 4 |
| 146 |
0x80485a5 is in main (test.cc:4). |
| 147 |
3 int *array = new int [42] ; |
| 148 |
4 int *foo = new int; |
| 149 |
This means that total of two allocations happened, in two different places. |
| 150 |
|
| 151 |
First a delete error is shown: you allocated some memory using new[] but you |
| 152 |
freed it using delete. leak-analyze will show where you allocated the memory and where you freed it. |
| 153 |
|
| 154 |
Afterwards each allocation is shown in turn. There was 1 allocation from this |
| 155 |
line of code (test.cc:3), and it was 168 bytes in size. Note that of the two |
| 156 |
lines of code shown, it's the bottom one that created the allocation. |
| 157 |
|
| 158 |
That's all there is to it - now you should find those memory leaks, fix them |
| 159 |
and rerun Leak tracer. |
| 160 |
|
| 161 |
</PRE><h3><a name="chap6">Shared libraries and objects</a></h3><PRE> |
| 162 |
If you want to analyze the leaks in shared libraries in your file, it may be |
| 163 |
necessary to make leak-analyze run your program and thus load the shared |
| 164 |
libraries before searching for addresses. |
| 165 |
|
| 166 |
To do that, run leak-analyze with the program name, leak name AND another |
| 167 |
argument which is where to set the breakpoint, e.g.: |
| 168 |
|
| 169 |
leak-analyze myprog leak.out main |
| 170 |
|
| 171 |
This will make leak-analyze tell gdb to set a breakpoint on "main" and then |
| 172 |
run the program. After the analysis is complete, the program will be killed. |
| 173 |
|
| 174 |
If you want to load some shared libraries, you can set a breakpoint on a |
| 175 |
different location, e.g. main.cc:42 if you know that once line 42 is reached, |
| 176 |
all shared objects have been loaded. |
| 177 |
|
| 178 |
If your program needs some command line arguments, supply them after "main". |
| 179 |
</PRE><h3><a name="chap7">Licensing</a></h3><PRE> |
| 180 |
LeakTracer is public domain (i.e. do with it whatever you feel like). |
| 181 |
|
| 182 |
</PRE><h3><a name="chap8">Credits</a></h3><PRE> |
| 183 |
Initial version of LeakTracer was written by Erwin Andreasen. Henner Zeller |
| 184 |
([email protected]) contributed a rewrite of the code which |
| 185 |
introduced dynamic loading of LeakTracer and more. |
| 186 |
</PRE><h3><a name="chap9">Revision history</a></h3><PRE> |
| 187 |
February 21, 1999 v1.0 - only tested internally |
| 188 |
February 23, 1999 v1.1 - added operator new[] / delete[] |
| 189 |
February 23, 1999 v1.2 - Oops, forgot to free() the memory.. |
| 190 |
February 26, 1999 v1.3 - allow delete 0 |
| 191 |
March 27, 1999 v1.4 - Allow %p format without leading 0x for non-GNU |
| 192 |
libc. Option to leak-analyze to run the program. |
| 193 |
July 21, 1999 v1.5 - Fix for the above suggested by Alan Gonzalez |
| 194 |
August 21, 2000 v1.6 - use a destructor instead of |
| 195 |
__attribute__(destructor) |
| 196 |
November 19, 2000 v2.0 - Rewrite by Henner Zeller introduces LD_PRELOAD |
| 197 |
and much more |
| 198 |
February 27, 2001 v2.1 - Further update by Henner: optional thread safety, |
| 199 |
choose what should make LeakTracer abort(), better |
| 200 |
tracing of delete on non-new'ed pointers |
| 201 |
March 2, 2001 v2.2 - Another updated by Henner: hash table to increase |
| 202 |
performance with many allocations |
| 203 |
June 13, 2001 v2.3 - Made LT more resistant to being called before init |
| 204 |
and after destruction |
| 205 |
|
| 206 |
Authors: Erwin Andreasen <[email protected]> |
| 207 |
Henner Zeller <[email protected]> |
| 208 |
Homepage: <a href="http://www.andreasen.org/LeakTracer/">http://www.andreasen.org/LeakTracer/</a> |
| 209 |
|
| 210 |
</PRE> |