mpatrol.txt

debug source code under unix platform.

This file documents mpatrol, a library for controlling and tracing
dynamic memory allocations.

   Copyright (C) 1997-2002 Graeme S. Roy <[e-mail]>

   This is edition 2.13 of the mpatrol manual for version 1.4.8, 8th
January, 2002.

   Permission is granted to make and distribute verbatim copies of this
manual provided the copyright notice and this permission notice are
preserved on all copies.

   Permission is granted to copy and distribute modified versions of
this manual under the conditions for verbatim copying, provided that
the entire resulting derived work is distributed under the terms of a
permission notice identical to this one.

   Permission is granted to copy and distribute translations of this
manual into another language, under the above conditions for modified
versions, except that this permission notice may be stated in a
translation approved by the Free Software Foundation.

   All product names mentioned in the documentation and source code for
this library are the trademarks of their respective owners.


...Table of Contents...
mpatrol
*******

                                 _                     _
                                | |                   | |
 ____ ___    _____     _____   _| |_   _____   ____   | |
|  _ ~ _ \  |  __ \   / __  | |_   _| |  ___| / __ \  | |
| | | | | | | |  | | | |  | |   | |   | |    | |  | | | |
| | | | | | | |__| | | |__| |   | |   | |    | |__| | | |
|_| |_| |_| |  ___/   \_____|   |_|   |_|     \____/  |_|
            | |
            |_|

   This document describes mpatrol, a library for controlling and
tracing dynamic memory allocations.

   This is edition 2.13 of the mpatrol manual for version 1.4.8, 8th
January, 2002.

Foreword
********

   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 (*note 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 (*note Installation::) and Examples (*note 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 (*note 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 (*note
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://www.cbmamiga.demon.co.uk/mpatrol/', and any
correspondence relating to mpatrol (bug reports, enhancement requests,
compliments, etc.) should be sent to <[e-mail]>.
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.  I can also be reached at
<[e-mail]> but that is my work e-mail address.  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 (<[e-mail]>)
for his help on reading debugging information from object files via the
GNU BFD library, and Adam Zell (<[e-mail]>) for helping with
patching the dynamic linker support functions for loading shared
libraries.  Both Alexander Barton (<[e-mail]>) and Dave
Gibson (<[e-mail]>) helped to make mpatrol thread-safe.
Roger Keane (<[e-mail]>) provided the perl code in the `mpsym'
command and also the idea for the `MP_USE_ATEXIT' feature macro.  Steve
McIntyre (<[e-mail]>) helped by diagnosing the
`fork()' problem and provided example code on how to fix it.  Peter
Zijlstra (<[e-mail]>) contributed code to enhance stack
traces for errors.

   Boris Makushkin (<[e-mail]>) requested, helped with, and
provided initial testing for the FreeBSD port, and Ivan Finch
(<[e-mail]>), Gerrit Bruchhaeuser (<[e-mail]>)
and Andreas Schallenberg
(<[e-mail]>) did the same for
the Tru64 and SuSE ports.  Both Aleksandar Donev (<[e-mail]>)
and Van Snyder (<[e-mail]>) provided suggestions and
code for using mpatrol with FORTRAN.  Michael Anthony (<[e-mail]>)
wrote the profdiff tool and Jerome Marant (<[e-mail]>) did the
Debian GNU/Linux port.

   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.

1 Overview
**********

   The mpatrol library is yet another link library that attempts to
diagnose run-time errors that are caused by the wrong use of
dynamically allocated memory.  If you don't know what the `malloc()'
function or `operator new[]' do then this library is probably not for
you.  You have to have a certain amount of programming expertise and a
knowledge of how to run a command line compiler and linker before you
should attempt to use this.

   Along with providing a comprehensive and configurable log of all
dynamic memory operations that occurred during the lifetime of a
program, the mpatrol library performs extensive checking to detect any
misuse of dynamically allocated memory.  All of this functionality can
be integrated into existing code through the inclusion of a single
header file at compile-time.  On UNIX and Windows platforms (and
AmigaOS when using `gcc') this may not even be necessary as the mpatrol
library can be linked with existing object files at link-time or, on
some platforms, even dynamically linked with existing programs at
run-time.

   All logging and tracing output from the mpatrol library is sent to a
separate log file in order to keep its diagnostics separate from any
that the program being tested might generate.  A wide variety of
library settings can also be changed at run-time via an environment
variable, thus removing the need to recompile or relink in order to
change the library's behaviour.

   A file containing a summary of the memory allocation profiling
statistics for a particular program can be produced by the mpatrol
library.  This file can then be read by a profiling tool which will
display a set of tables based upon the accumulated data.  The profiling
information includes summaries of all of the memory allocations listed
by size and the function that allocated them and a list of memory leaks
with the call stack of the allocating function.  It also includes a
graph of all memory allocations listed in tabular form, and an optional
graph specification file for later processing by the `dot' graph
visualisation package.

   A file containing a concise encoded trace of all memory allocations,
reallocations and deallocations made by a program can also be produced
by the mpatrol library.  This file can then be read by a tracing tool
which will decode the trace and display the events in tabular or
graphical form, and also display any relevant statistics that could be
calculated.

   The mpatrol library has been designed with the intention of
replacing calls to existing C and C++ memory allocation functions as
seamlessly as possible, but in many cases that may not be possible and
slight code modifications may be required.  However, a preprocessor
macro containing the version of the mpatrol library is provided for the
purposes of conditional compilation so that release builds and debug
builds can be easily automated.

2 Features
**********

   An overall list of features contained in the mpatrol library is
given below.  This is not intended to be exhaustive since the best way
to see what the library does is to read the documentation and try it
out.

   * Written for 32-bit and 64-bit UNIX, AmigaOS, Windows and Netware
     platforms.  Contains direct support for (and takes advantage of
     most of the features of) AIX, DG/UX, DRS/NX, DYNIX/ptx, FreeBSD,
     HP/UX, IRIX, Linux, LynxOS, NetBSD, OpenBSD, SINIX, Solaris,
     SunOS, Tru64 and UnixWare.  Also contains target-specific code to
     take advantage of Alpha, Intel 80x86, Motorola 680x0 and 88xx0,
     MIPS, HP PA/RISC, IBM RS/6000, PowerPC and SPARC processors.

   * Has the ability to read symbols from executable files and shared
     libraries in the `a.out', COFF, XCOFF, ELF32, ELF64 and Windows
     Portable Executable file formats, and if the GNU BFD library is
     available then the mpatrol library can read symbols from all of
     the file formats that it has support for as well.  Can also liase
     with AIX, BSD-based, HP/UX, IRIX, OSF, SVR4-based and Windows
     dynamic linkers in order to find out information about shared
     libraries.

   * Can be built to allocate memory from a fixed-sized static array
     rather than using heap memory from the system.

   * Can be built as archive, shared and/or thread-safe libraries on
     systems that support them, or even as one large object file.  A
     lint library can also be built from the mpatrol library on UNIX
     platforms.

   * A release version of the mpatrol library is provided, which has
     the same functional interface, but does not contain any of
     mpatrol's debugging, tracing or profiling features.  It is
     intended to be used to quickly remove the mpatrol library.

   * Details of memory allocations and free memory are stored
     internally as a tree structure for speed and also to allow the
     best fit allocation algorithm to be used.  This also enables the