tools/leaky/leaky.html

   1 <!doctype html public "-//w3c//dtd html 4.0 transitional//en">
   2 <html>
   3 <head>
   4    <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
   5    <meta name="GENERATOR" content="Mozilla/4.61 [en] (X11; I; Linux 2.2.5-22 i686) [Netscape]">
   6    <title>Leaky</title>
   7 </head>
   8 <body text="#000000" bgcolor="#FFFFFF" link="#0000EE" vlink="#551A8B" alink="#FF0000">
   9
  10 <center><b><font face="Arial,Helvetica"><font size=+2>Leaky</font></font></b></center>
  11
  12 <p>Leaky is a program which will help you find memory leaks, and as of
  13 late, help you debug reference count problems with xpcom objects.
  14 <p><b><font face="Arial,Helvetica"><font size=+2>Get the Source</font></font></b>
  15 <p>Leaky is not currently part of the default SeaMonkey module,
  16 <br>you will need to explicitly pull the source:
  17 <br>&nbsp;
  18 <pre>&nbsp; cvs checkout mozilla/tools/leaky</pre>
  19 If there is enough demand, we can make this part of the default SeaMonkey
  20 module.
  21 <p><b><font face="Arial,Helvetica"><font size=+2>Building it</font></font></b>
  22 <br>&nbsp;
  23 <pre>&nbsp; ./configure --enable-leaky</pre>
  24 Top-of-tree build should Just Build It and leaky will show up in dist/bin.
  25 <p><b><font face="Arial,Helvetica"><font size=+2>Using Leaky</font></font></b>
  26 <p>After it has been built, you can use TestPreload and TestMalloc and
  27 ShowLibs to debug your implementation.
  28 <p>By setting the <tt>LIBMALLOC_LOG</tt> environment variable you control
  29 how much information is logged during the programs execution. See libmalloc.h
  30 for a definition of the values to use. If you are using <tt>LD_PRELOAD</tt>,
  31 here is one way to run your program:
  32 <blockquote><tt>env LD_PRELOAD=/full/path/to/libleaky.so LIBMALLOC_LOG=1
  33 my-program</tt></blockquote>
  34 The debugging malloc library creates two files, <tt>malloc-log</tt> and
  35 <tt>malloc-map</tt>.
  36 The malloc-log file can be quite large for large programs (e.g. mozilla)
  37 so be prepared to have a lot of disk space. The malloc-map is tiny.
  38 <p>Once your program has completed execution you can use leaky to look
  39 for memory leaks, or at least use it to dump the log. For memory leaks,
  40 you use leaky like this:
  41 <blockquote><tt>leaky -d &lt;program-name-goes-here> malloc-log</tt></blockquote>
  42 Leaky will then display all of the call sites where memory was leaked.
  43 To look at the entire log file contents, not just the leaks add "-a" to
  44 the arguments:
  45 <blockquote><tt>leaky -d -a &lt;program-name-goes-here> malloc-log</tt></blockquote>
  46 For debugging reference count issues, here is what I do:
  47 <ol>
  48 <li>
  49 Set LIBMALLOC_LOG to "8"</li>
  50
  51 <li>
  52 Modify your source code so that your class::Addref and class::Release methods
  53 call __log_addref and __log_release, as appropriate. See libmalloc.h for
  54 their signatures. If you are using mozilla, you no longer need to modify
  55 your source code with a debug build. See
  56 <a href="http://lxr.mozilla.org/seamonkey/source/xpcom/doc/MemoryTools.html">
  57 xpcom/doc/MemoryTools.html</a> for more info.
  58
  59 </li>
  60
  61 <li>
  62 Run your program so that you get the log data. Its often convenient to
  63 run your program in the debugger and then set a breakpoint at an interesting
  64 location where you think some object is being leaked or over-freed. Then
  65 when the debugger gets there tell it to execute DumpAddressMap. In gdb
  66 you do this:</li>
  67
  68 <ol>&nbsp;
  69 <br><tt>(gdb) p DumpAddressMap()</tt></ol>
  70
  71 <li>
  72 Then use leaky to capture the addref and release calls to a log file:</li>
  73
  74 <ol>&nbsp;
  75 <br><tt>leaky -d -a &lt;program-name-goes-here> malloc-log > log</tt></ol>
  76
  77 <li>
  78 Then use "grep" to search the log for a specific object by grepping for
  79 its memory address...</li>
  80
  81 <li>
  82 On a typical *short* run of mozilla, I'll end up with a malloc-log file
  83 of around 5 to 10 megabytes and the resulting converted log file will be
  84 10 to 20 times that so be prepared to have a lot of disk space. It helps
  85 a great deal to narrow down your problem space to reduce the log file size...</li>
  86 </ol>
  87
  88 <p><br>Leaky now has a "graph" output option. If you do this:
  89 <pre>&nbsp; leaky -gqx &lt;program-name-goes-here>&nbsp; malloc-log | sed -e 's/&amp;/&amp;/g' > /tmp/GQ0.html</pre>
  90 Then leaky will make a graph of the leaks [-g] and output that graph in
  91 xml format (currently actually html...) [-x]. I use sed to make it legitimate
  92 html and off it goes to a file.
  93 <p>If you throw file at viewer (recursion is cool) then it will present
  94 you with a treeview of the leaks that you can click on to open/close sections.
  95 Enjoy!
  96 <p><b><font face="Arial,Helvetica"><font size=+2>Command Line Options</font></font></b>
  97 <br>&nbsp;
  98 <table CELLSPACING=5 CELLPADDING=0 WIDTH="100%" NOSAVE >
  99 <tr>
 100 <td>-a</td>
 101
 102 <td>dump the entire log. This means all malloc's, free's, new's, delete's,
 103 addref's or release's will be displayed</td>
 104 </tr>
 105
 106 <tr>
 107 <td>-d</td>
 108
 109 <td>dump leaks (only one of -d, -R or -g can be used at a time)</td>
 110 </tr>
 111
 112 <tr>
 113 <td>-R</td>
 114
 115 <td>dump refcnts</td>
 116 </tr>
 117
 118 <tr>
 119 <td>&nbsp;</td>
 120
 121 <td>&nbsp;</td>
 122 </tr>
 123
 124 <tr>
 125 <td>-g</td>
 126
 127 <td>display a graph of leaks</td>
 128 </tr>
 129
 130 <tr>
 131 <td>-x</td>
 132
 133 <td>when displaying the graph with -g, use html output that can be fed
 134 into an html4+css+dom compliant viewer (like mozilla :-)</td>
 135 </tr>
 136
 137 <tr>
 138 <td>-r symbol</td>
 139
 140 <td>define a root for the graph dump. nodes in the graph above symbol will
 141 be hidden, thus reducing the depth of the graph making it easier to find
 142 deeper leaks.</td>
 143 </tr>
 144
 145 <tr>
 146 <td>&nbsp;</td>
 147
 148 <td>&nbsp;</td>
 149 </tr>
 150
 151 <tr>
 152 <td>-e symbol</td>
 153
 154 <td>exclude leaks that include symbol from treatment</td>
 155 </tr>
 156
 157 <tr>
 158 <td>-i symbol</td>
 159
 160 <td>include leaks that include symbol for treatment. If an includes are
 161 defined than only leaks which include the symbols will be processed. excludes
 162 will still apply to this reduced set of leaks</td>
 163 </tr>
 164
 165 <tr>
 166 <td>&nbsp;</td>
 167
 168 <td>&nbsp;</td>
 169 </tr>
 170
 171 <tr>
 172 <td>-A</td>
 173
 174 <td>show the address in the stack crawls, not just the symobls</td>
 175 </tr>
 176
 177 <tr>
 178 <td>-h num</td>
 179
 180 <td>set the size of the hash buckets used by leaksy dictionaries to &lt;num></td>
 181 </tr>
 182
 183 <tr>
 184 <td>-s depth</td>
 185
 186 <td>set the depth of the stack crawls shown when displaying stack crawls
 187 (any of the dumping modes except -g)</td>
 188 </tr>
 189
 190 <tr>
 191 <td>-q</td>
 192
 193 <td>make leaky quiet (don't dump the information about symbols being read
 194 and from which libraries)</td>
 195 </tr>
 196 </table>
 197
 198 <p><b><font face="Arial,Helvetica"><font size=+2>Porting to non-Intel/Linux</font></font></b>
 199 <br>&nbsp;
 200 <p>Initial version works only on x86 linux. To work on other platforms
 201 you will need to:
 202 <ol>
 203 <li>
 204 Implement <tt>CrawlStack()</tt> in libmalloc.cpp</li>
 205
 206 <li>
 207 Implement <tt>DumpAddressMap()</tt> in libmalloc.cpp and in ShowLibs.cpp</li>
 208
 209 <li>
 210 Either support LD_PRELOAD in your dynamic linker, <b>or</b></li>
 211
 212 <br>produce a library that wraps your libc malloc (see config.h for some
 213 clues)
 214 <li>
 215 Implement symbol table reading code (see coff.cpp, elf.cpp and bfd.cpp
 216 for examples; at the time of writing this document only bfd.cpp was known
 217 to work)</li>
 218 </ol>
 219
 220 <hr><!-- hhmts start -->Last modified: Sun Sep 26 13:15:33 PDT 1999<!-- hhmts end -->
 221 <br>Send comments to <i><a href="mailto:kipp@netscape.com">Kipp Hickman</a></i>
 222 <br>&nbsp;
 223 </body>
 224 </html>