mpatrol.html

debug source code under unix platform.

it.

<p>Finally, I'd like to thank Stephan Springl (<a href="mailto:[e-mail]">[e-mail]</a>) for
his help on reading debugging information from object files via the GNU BFD
library, and Adam Zell (<a href="mailto:[e-mail]">[e-mail]</a>) for helping with patching the
dynamic linker support functions for loading shared libraries.  Both Alexander
Barton (<a href="mailto:[e-mail]">[e-mail]</a>) and Dave Gibson
(<a href="mailto:[e-mail]">[e-mail]</a>) helped to make mpatrol thread-safe.  Roger
Keane (<a href="mailto:[e-mail]">[e-mail]</a>) provided the perl code in the <code>mpsym</code>
command and also the idea for the <code>MP_USE_ATEXIT</code> feature macro.  Steve
McIntyre (<a href="mailto:[e-mail]">[e-mail]</a>) helped by diagnosing the
<code>fork()</code> problem and provided example code on how to fix it.  Peter
Zijlstra (<a href="mailto:[e-mail]">[e-mail]</a>) contributed code to enhance stack
traces for errors.

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

<p>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!

<p>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.

<p>Happy debugging!

<p>Graeme Roy, 11th October, 1999.

<p>Edinburgh, Scotland.

<p><hr>
Node:<a name="Overview">Overview</a>,
Next:<a rel=next href="#Features">Features</a>,
Previous:<a rel=previous href="#Foreword">Foreword</a>,
Up:<a rel=up href="#Top">Top</a>
<br>

<h1>1 Overview</h1>

<p>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 <code>malloc()</code> function or <code>operator
new[]</code> 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.

<p>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 <code>gcc</code>) 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.

<p>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.

<p>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 <code>dot</code>
graph visualisation package.

<p>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.

<p>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.

<p><hr>
Node:<a name="Features">Features</a>,
Next:<a rel=next href="#Installation">Installation</a>,
Previous:<a rel=previous href="#Overview">Overview</a>,
Up:<a rel=up href="#Top">Top</a>
<br>

<h1>2 Features</h1>

<p>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.

<ul>
<li>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.

<li>Has the ability to read symbols from executable files and shared libraries in
the <code>a.out</code>, 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.

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

<li>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.

<li>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.

<li>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 library to perform intelligent resizing of memory
allocations and can be used to quickly determine if an address has been
allocated on the heap.

<li>Contains 19 replacement C dynamic memory allocation functions:

<p><table><tr align="left"><td><code>malloc()</code>
<td>ANSI
<td>Allocates memory. 
<br></tr><tr align="left"><td><code>calloc()</code>
<td>ANSI
<td>Allocates zero-filled memory. 
<br></tr><tr align="left"><td><code>memalign()</code>
<td>UNIX
<td>Allocates memory with a specified alignment. 
<br></tr><tr align="left"><td><code>valloc()</code>
<td>UNIX
<td>Allocates page-aligned memory. 
<br></tr><tr align="left"><td><code>pvalloc()</code>
<td>UNIX
<td>Allocates a number of pages. 
<br></tr><tr align="left"><td><code>alloca()</code>
<td>old
<td>Allocates temporary memory. 
<br></tr><tr align="left"><td><code>strdup()</code>
<td>UNIX
<td>Duplicates a string. 
<br></tr><tr align="left"><td><code>strndup()</code>
<td>old
<td>Duplicates a string with a maximum length. 
<br></tr><tr align="left"><td><code>strsave()</code>
<td>old
<td>Duplicates a string. 
<br></tr><tr align="left"><td><code>strnsave()</code>
<td>old
<td>Duplicates a string with a maximum length. 
<br></tr><tr align="left"><td><code>strdupa()</code>
<td>old
<td>Duplicates a string. 
<br></tr><tr align="left"><td><code>strndupa()</code>
<td>old
<td>Duplicates a string with a maximum length. 
<br></tr><tr align="left"><td><code>realloc()</code>
<td>ANSI
<td>Resizes memory. 
<br></tr><tr align="left"><td><code>reallocf()</code>
<td>BSD
<td>Resizes memory and frees on failure. 
<br></tr><tr align="left"><td><code>recalloc()</code>
<td>old
<td>Resizes memory allocated by <code>calloc()</code>. 
<br></tr><tr align="left"><td><code>expand()</code>
<td>old
<td>Resizes memory but does not relocate it. 
<br></tr><tr align="left"><td><code>free()</code>
<td>ANSI
<td>Frees memory. 
<br></tr><tr align="left"><td><code>cfree()</code>
<td>old
<td>Frees memory allocated by <code>calloc()</code>. 
<br></tr><tr align="left"><td><code>dealloca()</code>
<td>new
<td>Explicitly frees temporary memory.
<br></tr></table>

<li>Contains 5 replacement C dynamic memory extension functions:

<p><table><tr align="left"><td><code>xmalloc()</code>
<td>Allocates memory without failure. 
<br></tr><tr align="left"><td><code>xcalloc()</code>
<td>Allocates zero-filled memory without failure. 
<br></tr><tr align="left"><td><code>xstrdup()</code>
<td>Duplicates a string without failure. 
<br></tr><tr align="left"><td><code>xrealloc()</code>
<td>Resizes memory without failure. 
<br></tr><tr align="left"><td><code>xfree()</code>
<td>Frees memory.
<br></tr></table>

<li>Contains 6 replacement C dynamic memory alternative functions:

<p><table><tr align="left"><td><code>MP_MALLOC()</code>
<td>Allocates memory without failure. 
<br></tr><tr align="left"><td><code>MP_CALLOC()</code>
<td>Allocates zero-filled memory without failure. 
<br></tr><tr align="left"><td><code>MP_STRDUP()</code>
<td>Duplicates a string without failure. 
<br></tr><tr align="left"><td><code>MP_REALLOC()</code>
<td>Resizes memory without failure. 
<br></tr><tr align="left"><td><code>MP_FREE()</code>
<td>Frees memory. 
<br></tr><tr align="left"><td><code>MP_FAILURE()</code>
<td>Sets the allocation failure handler.
<br></tr></table>

<li>Contains 4 replacement C++ dynamic memory allocation operators (in both
<em>throw</em> and <em>nothrow</em> forms):

<p><table><tr align="left"><td><code>operator new</code>
<td>Allocates memory. 
<br></tr><tr align="left"><td><code>operator new[]</code>
<td>Allocates memory for an array. 
<br></tr><tr align="left"><td><code>operator delete</code>
<td>Frees memory. 
<br></tr><tr align="left"><td><code>operator delete[]</code>
<td>Frees memory allocated by <code>operator new[]</code>.