mpatrol.texi

debug source code under unix platform.

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 @command{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 @command{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.

@node Features, Installation, Overview, Top
@chapter Features
@cindex mpatrol features
@cindex 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.

@itemize @bullet
@item
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.

@item
Has the ability to read symbols from executable files and shared libraries in
the @file{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.

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

@cindex archive library
@cindex library, archive
@cindex shared library
@cindex library, shared
@cindex thread-safe library
@cindex library, thread-safe
@item
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.

@item
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.

@item
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.

@item
Contains 19 replacement C dynamic memory allocation functions:

@multitable @columnfractions .2 .1 .7
@item @code{malloc()}
@tab ANSI
@tab Allocates memory.
@item @code{calloc()}
@tab ANSI
@tab Allocates zero-filled memory.
@item @code{memalign()}
@tab UNIX
@tab Allocates memory with a specified alignment.
@item @code{valloc()}
@tab UNIX
@tab Allocates page-aligned memory.
@item @code{pvalloc()}
@tab UNIX
@tab Allocates a number of pages.
@item @code{alloca()}
@tab old
@tab Allocates temporary memory.
@item @code{strdup()}
@tab UNIX
@tab Duplicates a string.
@item @code{strndup()}
@tab old
@tab Duplicates a string with a maximum length.
@item @code{strsave()}
@tab old
@tab Duplicates a string.
@item @code{strnsave()}
@tab old
@tab Duplicates a string with a maximum length.
@item @code{strdupa()}
@tab old
@tab Duplicates a string.
@item @code{strndupa()}
@tab old
@tab Duplicates a string with a maximum length.
@item @code{realloc()}
@tab ANSI
@tab Resizes memory.
@item @code{reallocf()}
@tab BSD
@tab Resizes memory and frees on failure.
@item @code{recalloc()}
@tab old
@tab Resizes memory allocated by @code{calloc()}.
@item @code{expand()}
@tab old
@tab Resizes memory but does not relocate it.
@item @code{free()}
@tab ANSI
@tab Frees memory.
@item @code{cfree()}
@tab old
@tab Frees memory allocated by @code{calloc()}.
@item @code{dealloca()}
@tab new
@tab Explicitly frees temporary memory.
@end multitable

@item
Contains 5 replacement C dynamic memory extension functions:

@multitable @columnfractions .3 .7
@item @code{xmalloc()}
@tab Allocates memory without failure.
@item @code{xcalloc()}
@tab Allocates zero-filled memory without failure.
@item @code{xstrdup()}
@tab Duplicates a string without failure.
@item @code{xrealloc()}
@tab Resizes memory without failure.
@item @code{xfree()}
@tab Frees memory.
@end multitable

@item
Contains 6 replacement C dynamic memory alternative functions:

@multitable @columnfractions .3 .7
@item @code{MP_MALLOC()}
@tab Allocates memory without failure.
@item @code{MP_CALLOC()}
@tab Allocates zero-filled memory without failure.
@item @code{MP_STRDUP()}
@tab Duplicates a string without failure.
@item @code{MP_REALLOC()}
@tab Resizes memory without failure.
@item @code{MP_FREE()}
@tab Frees memory.
@item @code{MP_FAILURE()}
@tab Sets the allocation failure handler.
@end multitable

@item
Contains 4 replacement C++ dynamic memory allocation operators (in both
@emph{throw} and @emph{nothrow} forms):

@multitable @columnfractions .3 .7
@item @code{operator new}
@tab Allocates memory.
@item @code{operator new[]}
@tab Allocates memory for an array.
@item @code{operator delete}
@tab Frees memory.
@item @code{operator delete[]}
@tab Frees memory allocated by @code{operator new[]}.
@end multitable

@item
Contains 10 replacement C memory operation functions:

@multitable @columnfractions .2 .1 .7
@item @code{memset()}
@tab ANSI
@tab Fills memory with a specific byte.
@item @code{bzero()}
@tab UNIX
@tab Fills memory with the zero byte.
@item @code{memccpy()}
@tab UNIX
@tab Copies memory up to a specific byte.
@item @code{memcpy()}
@tab ANSI
@tab Copies non-overlapping memory.
@item @code{memmove()}
@tab ANSI
@tab Copies possibly-overlapping memory.
@item @code{bcopy()}
@tab UNIX
@tab Copies possibly-overlapping memory.
@item @code{memcmp()}
@tab ANSI
@tab Compares two blocks of memory.
@item @code{bcmp()}
@tab UNIX
@tab Compares two blocks of memory.
@item @code{memchr()}
@tab ANSI
@tab Searches memory for a specific byte.
@item @code{memmem()}
@tab UNIX
@tab Searches memory for specific bytes.
@end multitable

@item
All of the above functions can also be defined with an additional underscore
prepended to their external name in order to catch all uses of these functions
in the system and third-party libraries.

@item
Contains support for a user-defined low-memory handler function, including a
replacement for the C++ function, @code{set_new_handler()}.

@item
The C++ dynamic memory allocation operators make use of the preprocessor in
order to obtain source-level information.  If this causes problems then
replacement operator names may be used so that the existing operators will still
work.

@item
Contains support for automatically registering any functions whose names begin
with @samp{__mp_init_} and @samp{__mp_fini_} to be called when the mpatrol
library is initialised and terminated respectively.  A function is also provided
to register additional functions to be called when the mpatrol library
terminates.

@item
Contains support for user-defined prologue and epilogue callback functions,
which get called before and after every memory allocation, reallocation or
deallocation.

@item
A function is provided to return as much information as possible about a given
memory allocation or free block, and can be called at any time during program
execution.  A similar function is also provided for calling from within a
debugger and an example command file is provided for use with @command{gdb}.

@item
A function is provided to display library settings and heap usage statistics,
including peak memory usage.  This information is also displayed at program
termination, and can also be placed into a data structure at run-time via
another function.

@item
The library reads any user-controllable options at run-time from an environment
variable, but this does not have to be set as defaults will then be used.  This
prevents having to recompile anything in order to change any library settings.
An option exists to display a quick-reference summary of all of the recognised
options to the standard error file stream.  Library settings can also be set and
read from within user code after the library has been initialised by calling two