mpatrol.html

debug source code under unix platform.

<li>A function is provided to take a snapshot of the heap at the current point in
execution.  The value returned by this function can then be used to pinpoint
the differences in heap allocation details between that point and a later point
in the program.

<li>Functions are provided to iterate across all of the current heap allocations
and call a user-defined callback function for each one they find.

<li>A leak table is provided, which records a flat profile of memory allocation
behaviour between two points in a program and is keyed by source file location. 
Memory allocation events can either be recorded in the leak table automatically
via a run-time option or the leak table can be manipulated through several
functions.

<li>Functions are provided to write user-defined information directly to the mpatrol
log file, as well as hexadecimal memory dumps of any memory location.

<li>Options exist to display all freed and unfreed memory allocations at program
termination in order to detect memory leaks, as well as all free memory blocks. 
A separate program is also provided for locating memory leaks in unfinished log
files.

<li>An option exists to abort the program with a failure condition if there are more
than a specified number of unfreed memory allocations at program termination. 
This could be useful for batch testing in order to check that all tests free up
most of their allocated memory.

<li>Memory allocations can be <em>marked</em> to indicate to the mpatrol library that
they should remain allocated for the lifetime of the program and should not be
freed or be listed as a memory leak.

<li>Functions always report if their arguments are illegal in order to pinpoint any
errors, and options exist to perform rigorous checking of arguments when
allocating, reallocating and freeing memory.  In addition, checking is performed
to ensure that memory allocated by <code>operator new[]</code> is not freed with
<code>free()</code> for example.

<li>The type of function performing a memory allocation is always stored along with
the allocation, as well as the file and line number it was called from.  If
compiled with <code>gcc</code>, the function name will also be stored and the
thread identifier will be stored if using the thread-safe library.

<li>The library uses a header file to redefine the memory allocation functions as
macros in order to obtain more information about where they were called from. 
This is not strictly required on UNIX and Windows platforms (and AmigaOS when
using <code>gcc</code>), since the library automatically redefines the default
system memory allocation functions.  All redefinitions in the header can also
be disabled by defining the <code>NDEBUG</code> preprocessor macro, which also
disables the effect of calling any mpatrol library function.

<li>A command is supplied to run a program that was linked with the mpatrol library
with any specified options on the command line.  On some UNIX platforms, an
option also exists to override the default memory allocation routines for any
dynamically-linked program that was not previously linked with the mpatrol
library.

<li>The mpatrol library can be built to liaise with Parasoft Inuse, a commercial
graphical memory usage tool that can display the current memory map of a running
process.  Inuse is supplied with Parasoft Insure++.

<li>Comes with a library of tools that are built on top of the mpatrol library and
can be used to extend it for specific applications.

<li>An automake macro is provided to ease the integration of mpatrol into a new or
existing project.

<li>A small tool is provided to read a dictionary file and display all of the words
that can be represented in hexadecimal form.  Such hexadecimal constants can be
used to initialise variables in user programs in order to aid debugging.

<li>The library and tools can be built using the GNU autoconf, automake and libtool
utilities.  Build scripts are also supplied to build both installation packages
and binary distributions.  A Linux Software Map file is also provided.

<li>A small test suite is provided in order to test basic features.

<li>User documentation is currently available in TeXinfo format as well as UNIX
manual pages and a quick reference card.  The source code for the library and
tools can also be formatted for a printed manual. 
</ul>

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

<h1>3 Installation</h1>

<p>The mpatrol library was initially developed on an Amiga 4000/040 running AmigaOS
3.1.  I then installed Red Hat Linux 5.1 on my Amiga and added support for
Linux/m68k.  I've now just recently purchased a Dell Inspiron 7500 Notebook PC
and put my Amiga in retirement, so development will now continue on Red Hat
Linux 6.2 and above on the Intel platform.  I've tried my best to make it as
easy as possible to build and install mpatrol on any system, but it isn't
likely to run smoothly for everybody.  However, there shouldn't be any major
problems if you perform the following steps.

<p>Note that if you want to check the integrity of the files that came with the
mpatrol distribution you can use the <code>CHECKSUMS</code> file in the <code>mpatrol</code>
base directory.  You must have the <code>md5sum</code> command installed on your
system in order to make use of this file.

<p>If you wish to use GNU autoconf, automake and libtool to build and install
mpatrol you may do so by entering the <code>pkg/auto</code> directory and typing
<code>./setup</code>.  This will construct the directory structure that is required
by these tools and will also create a <code>configure</code> script.  Please see the
<code>INSTALL</code> file in that directory for information on how to proceed.  Note
that you can clean up the <code>pkg/auto</code> directory by typing <code>make
distclean</code> (if the <code>configure</code> script has already been run) followed by
<code>./cleanup</code>.

<p>For a manual installation, perform the following steps.

<ol type=1 start=1>
</p><li>Go into the <code>build</code> directory and then into the appropriate subdirectory
for your system.

<li>Edit the <code>Makefile</code> in that directory and check that it is using the
appropriate compiler and build tools.  The <code>CC</code> macro specifies the
compiler<a rel=footnote href="#fn-1"><sup>1</sup></a>, the <code>AR</code>
macro specifies the tool used to build the archive library and the <code>LD</code>
macro specifies the tool to build the shared library.  The <code>CFLAGS</code> macro
specifies compiler options that are always to be used, the <code>OFLAGS</code> macro
specifies optimisation options for the compiler, the <code>SFLAGS</code> macro
specifies options to be passed to the compiler when building a shared library
and the <code>TFLAGS</code> macro specifies options to be passed to the compiler when
building a thread-safe library.  You may also need to change the library names
and library build commands on different systems.

<p>Note that the generic UNIX <code>Makefile</code> contains a macro called <code>GUISUP</code>
which is set to <code>false</code> by default.  If it is set to <code>true</code> then the
<code>mptrace</code> command will be built with GUI support enabled.  However,
your system must contain the correct header files and libraries in order to
support this.

</p><li>Use the <code>make</code> command (or equivalent) to build the mpatrol library in
archive form.  The <code>all</code> target builds all possible combinations of the
mpatrol library for your system.  The <code>clean</code> target removes all relevant
object files from the current directory, while the <code>clobber</code> target also
removes all libraries that have been built from the current directory.  On some
UNIX platforms, the <code>lint</code> target will build a <code>lint</code> library for
the mpatrol library.

<li>If the mpatrol library is to be built with support for Parasoft Inuse then the
<code>MP_INUSE_SUPPORT</code> preprocessor macro must be defined in the
<code>CFLAGS</code> portion of the <code>Makefile</code> before building.  This will ensure
that Inuse will be notified of every memory allocation, reallocation and
deallocation, but the Insure++ runtime library will also have to be linked in
with any program that uses mpatrol.

<li>Copy all of the libraries that have been built into your local library
directory.  If there were symbolic links created in the <code>build</code> directory
then these should be recreated in the local library directory rather than simply
copying them.  You may need to run a command such as <code>ldconfig</code> in order
for the system to recognise the newly-installed libraries, and you may also need
to add the filename of the directory containing the newly-installed libraries to
an environment variable such as <code>LD_LIBRARY_PATH</code> if you installed the
libraries in a non-standard location.

<li>Copy the <code>mpatrol</code>, <code>mprof</code>, <code>mptrace</code> and
<code>mleak</code> programs that have been built into your local bin directory. 
You may also wish to copy the <code>mpsym</code>, <code>mpedit</code> and
<code>hexwords</code> commands to your local bin directory as well if your system
supports Bourne shell scripts.

<li>Go up two directory levels into the <code>src</code> directory and copy the
<code>mpatrol.h</code>, <code>mpalloc.h</code> and <code>mpdebug.h</code> header files into your
local include directory.

<li>Go up one directory level into the <code>tools</code> directory and copy all of the
header files into the <code>mpatrol</code> subdirectory (which you'll need to create)
in your local include directory.

<li>On UNIX platforms, go up one directory level into the <code>man</code> directory and
copy the <code>man1</code> and <code>man3</code> subdirectories to your local man directory. 
Unfortunately, the location for manual pages varies from system to system so you
may or may not also be able to copy the <code>cat1</code> and <code>cat3</code>
subdirectories as well.  The <code>man*</code> subdirectories contain the unformatted
manual pages while the <code>cat*</code> subdirectories contain the formatted manual
pages.

<li>Go up one directory level into the <code>doc</code> directory and examine the files
located there.  The <code>mpatrol.texi</code> file contains the TeXinfo source for
this manual and can be translated into a wide variety of documentation formats. 
The <code>refcard.tex</code> file contains the LaTeX source for the quick reference
card and can be translated into formats suitable for printing onto a few pages. 
There should already be translated files in the <code>doc</code> directory, but if not
you will have to generate them yourself using the <code>Makefile</code> provided.  You
can then install or print these documents.

<p>The mpatrol library source code can also be formatted for a printed manual for
later perusal.  The <code>source</code> target in the <code>Makefile</code> within the
<code>doc</code> directory can be used to build the source code documentation in DVI,
postscript and PDF formats, but be prepared for a large number of pages!

<p>If you are not installing on a system that supports UNIX manual pages then you
should also check in the <code>man</code> directory to ensure that there are
alternative formats for the mpatrol manual pages that you can install.  If not,
you will have to generate them yourself using the <code>Makefile</code> provided.
</ol>

<p>Alternatively, the <code>pkg</code> directory contains files that can be used to
automatically generate a <em>package</em> in a specific format suitable for
installation on a system.  Four package formats (PKG, SD/UX, RPM and Debian) and
three archive formats are currently supported (generic tape archive, LhA and
ZIP).

<p>The first package format is generally used on UNIX SVR4 systems, while the
second is used on HP/UX systems.  The RPM and Debian package formats were
introduced by Red Hat and Debian respectively for use in their Linux
distributions.

<p>The generic tape archive can be used as a distribution for UNIX systems where no
package format is supported, but it does not contain information on how to
install the files on the system once they have been extracted from the
distribution.  The LhA and ZIP formats are also roughly the same, but the LhA
format is intended for Amiga systems and is used for Aminet distributions, while
the ZIP format is intended for Windows systems and is used for WinSite
distributions.

<p>You should really know what you are doing before you attempt to build a package,
and you should also be aware that some of the package files may need to be
modified before you begin.

<p>In addition, a Linux Software Map index file exists in the <code>pkg/lsm</code>
directory.

<p>Note that the <code>extra</code> directory that comes with the mpatrol distribution
contains several prototype configuration files for certain third-party programs. 
These files should be examined so that you can decide whether to integrate their
contents into your existing configuration files.  The purpose of each file is
described in the relevant sections of this manual.

<p><hr>
Node:<a name="Integration">Integration</a>,
Next:<a rel=next href="#Memory%20allocations">Memory allocations</a>,
Previous:<a rel=previous href="#Installation">Installation</a>,
Up:<a rel=up href="#Top">Top</a>
<br>

<h1>4 Integration</h1>