I first started writing this library a few years ago when the company I work for sent me out to a customer who had reported a memory leak, which he expected was coming from the code generated by our C++ compiler. A few years on and the library has changed dramatically from its first beginnings, but I thought I'd release it publicly in case anyone else found it useful.
When writing the library, I placed more emphasis on the quantity and quality of information about allocated memory rather than the speed and efficiency of allocating the actual memory. This means that the library will use dramatically more memory than normal dynamic memory allocation libraries and can slow down to a crawl depending on which options you use. However, the end results are likely to be accurate and reliable, and in most cases the library will run quite happily at a sane speed.
The mpatrol library is by no means the only library of its kind. Solaris has no less that 6 different malloc libraries, and there are plenty available as freeware or as commercial products. Try to keep in mind that mpatrol comes with absolutely no warranty and so if it doesn't work for you and you need a fast solution, try some of the other libraries or products available. I have listed some of the most popular at the end of this manual (see Related software).
This manual is arranged so that complete reference material on the mpatrol library can be found in the appendices, while introductory and background material can be found in the preceding chapters and sections. For readers who wish to delve right in and use the library, the Installation (see Installation) and Examples (see Examples) chapters should be enough to get started in combination with the quick reference card. Otherwise, this manual should be read from beginning to end in order to get the most out of the software it describes. Note that all of the output shown from the examples was produced on 32-bit environments, although mpatrol can be built to support 64-bit environments as well.
Due to their very nature, problems with dynamic memory allocations are notoriously difficult to reproduce and debug, and this is likely to be the case if you find a bug in the mpatrol library as it might be extremely hard to reproduce on another system. Details on how to report bugs are given elsewhere in this document (see Notes), but it would be very useful if you could try to provide as much information as possible when reporting a problem, and that includes having a look in the library source code to see if it's obvious what is wrong. However, please try to read the frequently asked questions (see Frequently asked questions) first in case your question or problem is covered there since they are usually updated every time I receive a question about mpatrol.
The latest version of the mpatrol library and this manual can always be found at http://sourceforge.net/projects/mpatrol/, and any correspondence relating to mpatrol (bug reports, enhancement requests, compliments, etc.) should be sent to graemeroy@users.sourceforge.net. I'd be very interested in hearing any success stories with using mpatrol to debug programs, since I get very little feedback apart from the occasional bug report. The mpatrol library is also registered at FreshMeat (http://freshmeat.net/projects/mpatrol/) and SourceForge (http://sourceforge.net/projects/mpatrol/) and several other software sites so you can receive notification of updates there as well. I normally only check my e-mail about once or twice a week, so don't expect an immediate response. There is also a discussion group at http://groups.yahoo.com/group/mpatrol/ where you can post mpatrol-related questions but you must first subscribe to the group before you can send mail to it.
Finally, I'd like to thank Stephan Springl for his help on reading debugging
information from object files via the GNU BFD library, and Adam Zell for
helping with patching the dynamic linker support functions for loading shared
libraries. Both Alexander Barton and Dave Gibson helped to make mpatrol
thread-safe. Roger Keane provided the perl code in the mpsym command
and also the idea for the MP_USE_ATEXIT feature macro. Steve McIntyre
helped by diagnosing the fork() problem and provided example code on how
to fix it. Peter Zijlstra contributed code to enhance stack traces for errors.
Boris Makushkin requested, helped with, and provided initial testing for the FreeBSD port, and Ivan Finch, Gerrit Bruchhaeuser and Andreas Schallenberg did the same for the Tru64 and SuSE ports. Both Aleksandar Donev and Van Snyder provided suggestions and code for using mpatrol with FORTRAN. Michael Anthony wrote the profdiff tool and Jerome Marant did the Debian GNU/Linux port. Robert Schmitt wrote a tutorial on how to use mpatrol on Windows platforms, located at http://www.codeguru.com/cpp/w-p/win32/tutorials/print.php/c12231.
If your native language is a language other than English, you can make use of the many web-based translation tools that are now available for free on the internet. These can be used to translate pages of the on-line mpatrol manual from English to your chosen language, and although they may not be perfect, they should be able to translate most of the important text and convey the general ideas across. Note that Gerrit Bruchhaeuser has written a tutorial on mpatrol in German which is available from http://www.c-handbuch.org/mpatrol.html.
In addition, after spending well over 2000 hours designing and programming mpatrol, my sanity would not have been preserved in the state it is in today were it not for the music of The Chemical Brothers, The Manic Street Preachers, Orbital and The Prodigy. You can now argue how sane I am depending on your musical tastes!
Oh, and always remember to do final release builds without the mpatrol library as the library is much slower than normal malloc implementations and uses much more memory.
Happy debugging!
Graeme Roy, 11th October, 1999.
Edinburgh, Scotland.