Debian Codegraph @

minorGems/util/development/leakTracer/README

raw
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