mpatrol.html

debug source code under unix platform.

<p>This section describes how to go about adding or removing the mpatrol library
from your code.  There are several levels for each category so it is worth
reading about each before proceeding.

<ul>
<li><a href="#Adding%20mpatrol">Adding mpatrol</a>:               Adding mpatrol to your program. 
<li><a href="#Removing%20mpatrol">Removing mpatrol</a>:             Removing mpatrol from your program. 
</ul>

<p><hr>
Node:<a name="Adding%20mpatrol">Adding mpatrol</a>,
Next:<a rel=next href="#Removing%20mpatrol">Removing mpatrol</a>,
Up:<a rel=up href="#Integration">Integration</a>
<br>

<h2>4.1 Adding mpatrol</h2>

<p>The following steps should allow you to easily integrate the mpatrol library
into an existing application, although some of them may not be available to do
on many platforms.  They are listed in the order of number of changes required
to modify existing code -- the last step will require a complete recompilation
of all your code.

<ol type=1 start=1>
</p><li>This step is currently only available on DYNIX/ptx, FreeBSD, IRIX, Linux,
NetBSD, OpenBSD, Solaris and Tru64 platforms and on DG/UX 4.20MU07<a rel=footnote href="#fn-2"><sup>2</sup></a> or later platforms with the <code>LD_PRELOAD</code>
feature.

<p>If your program or application has been dynamically linked with the system C
library (<code>libc.so</code>) or an alternative malloc shared library then you can
use the <code>--dynamic</code> option to the <code>mpatrol</code> command to override the
default definitions of <code>malloc()</code>, etc. at run-time without having to
relink your program.  If your program is multithreaded then you must also add
the <code>--threads</code> option to pick up the multithreaded shared libraries
instead.

<p>For example, if your program's executable file is called <code>testprog</code> and it
accepts an option specifying an input file, you can force the system's dynamic
linker to use mpatrol's versions of <code>malloc()</code>, etc. instead of the
default versions by typing:

<pre>mpatrol --dynamic ./testprog -i file
</pre>

<p>The resulting log file should be called <code>mpatrol.&lt;procid&gt;.log</code> by default
(where <var>procid</var> is the current process id), but if no such file exists after
running the <code>mpatrol</code> command then it will not be possible to force the
run-time linking of mpatrol functions to your program and you will have to
proceed to the next step.  Note that the <code>mpatrol</code> command overrides
any previous setting of the <code>MPATROL_OPTIONS</code> environment variable.

</p><li>This step is currently only available on UNIX and Windows platforms (and AmigaOS
when using <code>gcc</code>).

<p>You should be able to link in the mpatrol library when linking your program
without having to recompile any of your object files or libraries, but this will
only be worthwhile on systems where stack tracebacks are supported, otherwise
you should proceed to the next step since there will not be enough information
for you to tell where the calls to dynamic memory allocation functions took
place.

<p>Information on how to link the mpatrol library to an application is given at the
start of the examples (see <a href="#Examples">Examples</a>), but you should note that if your
program does not directly call any of the functions in the mpatrol library then
it will not be linked in and you will not see a log file being generated when
you run it.  You can force the linking of the mpatrol library by causing
<code>malloc()</code> to be undefined on the link line, usually through the use of the
<code>-u</code> linker option.

<p>If your program is multithreaded then you must use the thread-safe version of
the mpatrol library and possibly also link in the system threads library as
well.  Not doing this will usually result in your program failing somewhere in
the mpatrol library code.

</p><li>All of the following steps will require you to recompile some or all of your
code so that your code calls dynamic memory allocation functions from the
mpatrol library rather than the system C library.

<p>This first step is only available when using <code>gcc</code>.

<p>You can make use of the <code>gcc</code> option <code>-fcheck-memory-usage</code> which
instructs the compiler to place calls to error-checking functions before each
access to memory.  This can result in a dramatic slowdown of your code so you
may wish to limit the use of this option to a few source files, but it does
provide a very thorough method of ensuring that you do not access memory beyond
the bounds of a memory allocation or attempt to access free memory.  However,
be aware that the checks are only placed in the bodies of functions that have
been compiled with this option and are missing from all functions that have not. 
You must link in the mpatrol library when using this option, otherwise you will
get linker errors.

<p>The <code>-fcheck-memory-usage</code> option was added to <code>gcc</code> to support
GNU Checker, which can be considered to be the run-time system for this option. 
GNU Checker also includes the ability to detect reads from uninitialised memory,
something that mpatrol does not currently support, and deals with stack objects
as well.  GNU Checker cannot be used in conjunction with mpatrol.

</p><li>For this step, if you have a rough idea of where the function calls lie that you
would like to trace or test, you need only recompile the relevant source files. 
You should modify these source files to include the <code>mpatrol.h</code> header file
before any calls to dynamic memory allocation or memory operation functions.

<p>However, you should take particular care to ensure that all calls to memory
allocation functions in the mpatrol library will be matched by calls to memory
reallocation or deallocation functions in the mpatrol library, since if they are
unmatched then the log file will either fill up with errors complaining about
trying to free unknown allocations, or warnings about unfreed memory allocations
at the end of execution.

</p><li>This step requires you to recompile all of your source files to include the
<code>mpatrol.h</code> header file.  Obviously, this will take the longest amount of
time to integrate, but need not require you to change any source files if the
compiler you are using has a command line option to include a specific header
file before any source files.

<p>For example, <code>gcc</code> comes with a <code>-include</code> option which has this
feature, so if you had to recompile a source file called <code>test.c</code> then the
following command would allow you to include <code>mpatrol.h</code> without having
to modify the source file:

<pre>gcc -include /usr/local/include/mpatrol.h -c test.c
</pre>
</ol>

<p>In all cases, it will be desirable to compile your source files with
compiler-generated debugging information since that may be able to be used by
the <code>USEDEBUG</code> option or the <code>mpsym</code> command.  In addition, more
symbolic information will be available if the executable files have not had
their symbol tables stripped from them, although mpatrol can also fall back to
using the dynamic symbol table from dynamically linked executable files.

<p>Note that an automake macro is now provided to allow you to integrate mpatrol
into a new or existing project that uses the GNU autoconf and automake tools. 
It is located in <code>extra/mpatrol.m4</code>, which should be copied to the
directory containing all of the local autoconf and automake macros on your
system, usually <code>/usr/local/share/aclocal</code>.  The automake macro it defines
is called <code>AM_WITH_MPATROL</code>, which should be added to the libraries section
in the <code>configure.in</code> file for your project.  It takes one optional
parameter specifying whether mpatrol should be included in the project
(<code>yes</code>) or not (<code>no</code>).  This can also be specified as <code>threads</code>
if you wish to use the threadsafe version of the mpatrol library.  You can
override the value of the optional parameter with the <code>--with-mpatrol</code>
option to the resulting <code>configure</code> shell script.

<p>If you are using the <code>AM_WITH_MPATROL</code> automake macro then you may wish to
use the <code>mpdebug.h</code> header file instead of <code>mpatrol.h</code>.  This ensures
that the <code>MP_MALLOC()</code> family of functions are always defined, even if
libmpatrol or libmpalloc are unavailable.  It makes use of the
<code>HAVE_MPATROL</code> and <code>HAVE_MPALLOC</code> preprocessor macros that are
controlled by the automake macro, but in other respects behaves in exactly the
same way as <code>mpatrol.h</code>.

<p><hr>
Node:<a name="Removing%20mpatrol">Removing mpatrol</a>,
Previous:<a rel=previous href="#Adding%20mpatrol">Adding mpatrol</a>,
Up:<a rel=up href="#Integration">Integration</a>
<br>

<h2>4.2 Removing mpatrol</h2>

<p>Once you have ironed out all of the problems in your code with the help of the
mpatrol library, there will come a time where you wish to build your program
without any of its debugging features, either to improve the speed that it runs
at, or perhaps even for a release.  Choose one of the following steps to help
you remove the mpatrol library from your program (you only need to perform them
if you linked your program with the mpatrol library).

<ol type=1 start=1>
</p><li>The quickest way to remove the mpatrol library from your application is to
link with libmpalloc instead of libmpatrol.  This contains replacements for all
of the mpatrol library functions, either implementing memory allocation or
memory operation functions with the system C library, or doing nothing in the
functions which perform debugging, profiling or tracing.  This method is a very
quick way to remove the mpatrol library but will not result in very efficient
code.

<li>The next option is to recompile all of the source files which include the
<code>mpatrol.h</code> header file, but this time define the <code>NDEBUG</code>
preprocessor macro.  This automatically disables the redefinition of
<code>malloc()</code>, etc. and prevents calls being made to any mpatrol library
functions.  Obviously, this option is the most time-consuming of the two, but
will result in the complete removal of all references to the mpatrol library.

<li>The final option is to guard all of the mpatrol-specific code in your program
with a preprocessor macro, possibly called <code>HAVE_MPATROL</code>, and then
recompiling all of your source code with this macro undefined.  This is the best
option but relies on you having originally made these changes when you first
started integrating the mpatrol library into your program.
</ol>

<p>Note that if you used the <code>AM_WITH_MPATROL</code> automake macro as detailed in
the previous section to build your application then you should perform a clean
recompilation using the <code>--without-mpatrol</code> option to the
<code>configure</code> shell script in order to completely remove the mpatrol library.

<p>Note also that if you used the <code>-fcheck-memory-usage</code> option of the GNU
compiler to check all memory accesses then you must recompile without that
option in order for your program to run at a reasonable speed.

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

<h1>5 Memory allocations</h1>

<p>In the C and C++ programming languages there are generally three different types
of memory allocation that can be used to hold the contents of variables.  Other
programming languages such as Pascal, BASIC and FORTRAN also support some of
these types of allocation, although their implementations may be slightly
different.

<ul>
<li><a href="#Static%20memory%20allocations">Static memory allocations</a>:    Fixed location, fixed size. 
<li><a href="#Stack%20memory%20allocations">Stack memory allocations</a>:     Variable location, fixed size. 
<li><a href="#Dynamic%20memory%20allocations">Dynamic memory allocations</a>:   Variable location, variable size. 
</ul>

<p><hr>
Node:<a name="Static%20memory%20allocations">Static memory allocations</a>,
Next:<a rel=next href="#Stack%20memory%20allocations">Stack memory allocations</a>,
Up:<a rel=up href="#Memory%20allocations">Memory allocations</a>
<br>

<h2>5.1 Static memory allocations</h2>

<p>The first type of memory allocation is known as a <em>static memory
allocation</em>, which corresponds to file scope variables and local static
variables.  The addresses and sizes of these allocations are fixed at the time
of compilation<a rel=footnote href="#fn-3"><sup>3</sup></a> and so they can be
placed in a fixed-sized data area which then corresponds to a section within the
final linked executable file.  Such memory allocations are called static because
they do not vary in location or size during the lifetime of the program.

<p>There can be many types of data sections within an executable file; the three
most common are normal data, BSS data and read-only data.  BSS data contains
variables and arrays which are to be initialised to zero at run-time and so is
treated as a special case, since the actual contents