mpatrol.texi

debug source code under unix platform.

\input texinfo

@c mpatrol
@c A library for controlling and tracing dynamic memory allocations.
@c Copyright (C) 1997-2002 Graeme S. Roy <[e-mail]>
@c
@c This library is free software; you can redistribute it and/or
@c modify it under the terms of the GNU Library General Public
@c License as published by the Free Software Foundation; either
@c version 2 of the License, or (at your option) any later version.
@c
@c This library is distributed in the hope that it will be useful,
@c but WITHOUT ANY WARRANTY; without even the implied warranty of
@c MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
@c Library General Public License for more details.
@c
@c You should have received a copy of the GNU Library General Public
@c License along with this library; if not, write to the Free
@c Software Foundation, Inc., 59 Temple Place, Suite 330, Boston,
@c MA 02111-1307, USA.

@c $Id: mpatrol.texi,v 1.256 2002/01/08 22:07:02 graeme Exp $

@c %**start of header
@setfilename mpatrol.info
@settitle mpatrol
@setchapternewpage odd
@afourpaper
@finalout
@c %**end of header

@dircategory Programming tools
@direntry
* mpatrol: (mpatrol).           The mpatrol library.
@end direntry

@c Remember to change these after each revision!
@set EDITION 2.13
@set VERSION 1.4.8
@set UPDATED 8th January, 2002

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

Copyright @copyright{} 1997-2002 Graeme S. Roy @email{graeme.roy@@analog.com}

This is edition @value{EDITION} of the mpatrol manual for version
@value{VERSION}, @value{UPDATED}.

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.

@ignore
Permission is granted to process this file through TeX and print the results,
provided the printed document carries a copying permission notice identical to
this one except for the removal of this paragraph (this paragraph not being
relevant to the printed manual).
@end ignore

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.
@end ifinfo

@titlepage
@title mpatrol
@subtitle A library for controlling and tracing dynamic memory allocations
@subtitle Edition @value{EDITION} for mpatrol version @value{VERSION}
@subtitle @value{UPDATED}
@sp 5
@image{images/mpatrol}
@author Graeme S. Roy
@page
@vskip 0pt plus 1filll
Copyright @copyright{} 1997-2002 Graeme S. Roy <@email{graeme.roy@@analog.com}>

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.
@end titlepage

@contents

@node Top, Foreword, , (dir)
@top mpatrol

@ifinfo
@image{images/mpatrol}
@end ifinfo

@ifhtml
@image{images/mpatrol}
@end ifhtml

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

This is edition @value{EDITION} of the mpatrol manual for version
@value{VERSION}, @value{UPDATED}.

@menu
* Foreword::                    Motivation and feedback.
* Overview::                    Overview of mpatrol.
* Features::                    Features of mpatrol.
* Installation::                Building and installing.
* Integration::                 Debugging existing programs.
* Memory allocations::          Background.
* Operating system support::    Additional background.
* Using mpatrol::               Using the library.
* Tools::                       Additional tools.
* Utilities::                   External programs.
* Profiling::                   Memory allocation profiling.
* Tracing::                     Memory allocation tracing.
* Heap corruption::             Squashing those errors.
* Memory leaks::                Detection and identification.
* Improving performance::       Life beyond mpatrol.
* How it works::                Implementation details.
* Examples::                    Examples of usage.
* Tutorial::                    Complete example.
* Functions::                   Library functions.
* Environment::                 Library run-time options.
* Options::                     Command line options.
* Diagnostic messages::         Warnings and errors.
* Library performance::         Comparitive timings.
* File formats::                Output file layouts.
* Supported systems::           Known platforms that mpatrol runs on.
* Porting::                     How to port mpatrol to a new system.
* Notes::                       Known bugs and future enhancements.
* Frequently asked questions::  For answering specific problems.
* Related software::            Similar programs.
* References::                  Additional information.
* About the author::            Information about me.
* Copying::                     GNU Library General Public License.
* Function index::              Library functions.
* Index::                       Main index.
@end menu

@node Foreword, Overview, Top, Top
@unnumbered Foreword
@cindex 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.

@cindex warranty
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 (@pxref{Related software}).

@cindex manual layout
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
(@pxref{Installation}) and Examples (@pxref{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.

@cindex bug reports
@cindex reporting bugs
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 (@pxref{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
(@pxref{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.

@cindex contacting the author
@cindex author, contacting
@cindex getting updates
@cindex updates
@cindex FreshMeat
@cindex SourceForge
The latest version of the mpatrol library and this manual can always be found at
@uref{http://www.cbmamiga.demon.co.uk/mpatrol/}, and any correspondence relating
to mpatrol (bug reports, enhancement requests, compliments, etc.@:) should be
sent to @email{mpatrol@@cbmamiga.demon.co.uk}.  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 (@uref{http://freshmeat.net/projects/mpatrol/})
and SourceForge (@uref{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 @email{graeme.roy@@analog.com} but
that is my work e-mail address.  There is also a discussion group at
@uref{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.

@cindex acknowledgements
@cindex contributors
Finally, I'd like to thank Stephan Springl (@email{springl@@bfw-online.de}) for
his help on reading debugging information from object files via the GNU BFD
library, and Adam Zell (@email{zell@@best.com}) for helping with patching the
dynamic linker support functions for loading shared libraries.  Both Alexander
Barton (@email{abarton@@innotrac.com}) and Dave Gibson
(@email{david.gibson@@analog.com}) helped to make mpatrol thread-safe.  Roger
Keane (@email{rgr@@bcs-inc.com}) provided the perl code in the @command{mpsym}
command and also the idea for the @code{MP_USE_ATEXIT} feature macro.  Steve
McIntyre (@email{smcintyre@@allstor-sw.co.uk}) helped by diagnosing the
@code{fork()} problem and provided example code on how to fix it.  Peter
Zijlstra (@email{peter@@xlnt-software.com}) contributed code to enhance stack
traces for errors.

Boris Makushkin (@email{oberon@@antibiotic.ru}) requested, helped with, and
provided initial testing for the FreeBSD port, and Ivan Finch
(@email{i.finch@@rl.ac.uk}), Gerrit Bruchhaeuser
(@email{gbruchhaeuser@@orga.com}) and Andreas Schallenberg
(@email{andreas.schallenberg@@informatik.uni-oldenburg.de}) did the same for the
Tru64 and SuSE ports.  Both Aleksandar Donev (@email{donev@@pa.msu.edu}) and Van
Snyder (@email{vsnyder@@math.jpl.nasa.gov}) provided suggestions and code for
using mpatrol with FORTRAN.  Michael Anthony (@email{m@@xyzfind.com}) wrote the
profdiff tool and Jerome Marant (@email{jerome@@debian.org}) 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!

@cindex release builds
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.

@node Overview, Features, Foreword, Top
@chapter Overview
@cindex overview

@cindex mpatrol
@cindex mpatrol library
@cindex library, mpatrol
@cindex run-time errors
@cindex errors, run-time
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()} function or @code{operator