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