Debian Codegraph @

minorGems/util/development/leakTracer/README.html

raw
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>