mpatrol.texi

debug source code under unix platform.

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.

Information on how to link the mpatrol library to an application is given at the
start of the examples (@pxref{Examples}), 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()} to be undefined on the link line, usually through the use of the
@option{-u} linker option.

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.

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

This first step is only available when using @command{gcc}.

You can make use of the @command{gcc} option @option{-fcheck-memory-usage} 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.

The @option{-fcheck-memory-usage} option was added to @command{gcc} 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.

@item
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 @file{mpatrol.h} header file
before any calls to dynamic memory allocation or memory operation functions.

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.

@item
This step requires you to recompile all of your source files to include the
@file{mpatrol.h} 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.

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

@smallexample
gcc -include /usr/local/include/mpatrol.h -c test.c
@end smallexample
@end enumerate

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 @option{USEDEBUG} option or the @command{mpsym} 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.

@cindex AM_WITH_MPATROL
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 @file{extra/mpatrol.m4}, which should be copied to the
directory containing all of the local autoconf and automake macros on your
system, usually @file{/usr/local/share/aclocal}.  The automake macro it defines
is called @code{AM_WITH_MPATROL}, which should be added to the libraries section
in the @file{configure.in} file for your project.  It takes one optional
parameter specifying whether mpatrol should be included in the project
(@samp{yes}) or not (@samp{no}).  This can also be specified as @samp{threads}
if you wish to use the threadsafe version of the mpatrol library.  You can
override the value of the optional parameter with the @option{--with-mpatrol}
option to the resulting @file{configure} shell script.

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

@node Removing mpatrol, , Adding mpatrol, Integration
@section Removing mpatrol
@cindex removing mpatrol

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

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

@item
The next option is to recompile all of the source files which include the
@file{mpatrol.h} header file, but this time define the @code{NDEBUG}
preprocessor macro.  This automatically disables the redefinition of
@code{malloc()}, 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.

@item
The final option is to guard all of the mpatrol-specific code in your program
with a preprocessor macro, possibly called @code{HAVE_MPATROL}, 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.
@end enumerate

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

Note also that if you used the @option{-fcheck-memory-usage} 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.

@node Memory allocations, Operating system support, Integration, Top
@chapter Memory allocations
@cindex memory allocations

@cindex C
@cindex C++
@cindex Pascal
@cindex BASIC
@cindex FORTRAN
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.

@menu
* Static memory allocations::   Fixed location, fixed size.
* Stack memory allocations::    Variable location, fixed size.
* Dynamic memory allocations::  Variable location, variable size.
@end menu

@node Static memory allocations, Stack memory allocations, , Memory allocations
@section Static memory allocations
@cindex static memory allocations
@cindex memory allocations, static

@cindex file scope variables
@cindex variables, file scope
@cindex local static variables
@cindex variables, local static
The first type of memory allocation is known as a @emph{static memory
allocation}, which corresponds to file scope variables and local static
variables.  The addresses and sizes of these allocations are fixed at the time
of compilation@footnote{Or more accurately, at link time.} 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.

@cindex data sections
@cindex sections
@cindex BSS
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 of the section need not be
stored in the executable file.  Read-only data consists of constant variables
and arrays whose contents are guaranteed not to change when a program is being
run.  For example, on a typical SVR4 UNIX system the following variable
definitions would result in them being placed in the following sections:

@smallexample
int a;           /* BSS data */
int b = 1;       /* normal data */
const int c = 2; /* read-only data */
@end smallexample

@cindex tentative declarations
@cindex declarations, tentative
@cindex common variables
In C the first example would be considered a @emph{tentative} declaration, and
if there was no subsequent definition of that variable in the current
translation unit then it would become a @emph{common} variable in the resulting
object file.  When the object file gets linked with other object files, any
common variables with the same name become one variable, or take their
definition from a non-tentative definition of that variable.  In the former
case, the variable is placed in the BSS section.  Note that C++ has no support
for tentative declarations.

As all static memory allocations have sizes and address offsets that are known
at compile-time and are explicitly initialised, there is very little that can go
wrong with them.  Data can be read or written past the end of such variables,
but that is a common problem with all memory allocations and is generally easy
to locate in that case.  On systems that separate read-only data from normal
data, writing to a read-only variable can be quickly diagnosed at run-time.

@node Stack memory allocations, Dynamic memory allocations, Static memory allocations, Memory allocations
@section Stack memory allocations
@cindex stack memory allocations
@cindex memory allocations, stack

@cindex parameter variables
@cindex variables, parameter
@cindex call-by-value
@cindex non-static local variables
@cindex variables, non-static local
The second type of memory allocation is known as a @emph{stack memory
allocation}, which corresponds to non-static local variables and call-by-value
parameter variables.  The sizes of these allocations are fixed at the time of
compilation but their addresses will vary depending on when the function which
defines them is called.  Their contents are not immediately initialised, and
must be explicitly initialised by the programmer upon entry to the function or
when they become visible in scope.

@cindex stack
@cindex registers
Such memory allocations are placed in a system memory area called the
@emph{stack}, which is allocated per process@footnote{Or per thread on some
systems.} and generally grows down in memory.  When a function is called, the
state of the calling function must be preserved so that when the called function
returns, the calling function can resume execution.  That state is stored on the
stack, including all local variables and parameters.  The compiler generates
code to increase the size of the stack upon entry to a function, and decrease
the size of the stack upon exit from a function, as well as saving and restoring
the values of registers.

There are a few common problems using stack memory allocations, and most
generally involve uninitialised variables, which a good compiler can usually
diagnose at compile-time.  Some compilers also have options to initialise all
local variables with a bit pattern so that uninitialised stack variables will
cause program faults at run-time.  As with static memory allocations, there can
be problems with reading or writing past the end of stack variables, but as
their sizes are fixed these can usually easily be located.

@node Dynamic memory allocations, , Stack memory allocations, Memory allocations
@section Dynamic memory allocations
@cindex dynamic memory allocations
@cindex memory allocations, dynamic

The last type of memory allocation is known as a @emph{dynamic memory
allocation}, which corresponds to memory allocated via @code{malloc()} or
@code{operator new[]}.  The sizes, addresses and contents of such memory vary
at run-time and so can cause a lot of problems when trying to diagnose a fault
in a program.  These memory allocations are called dynamic memory allocations
because their location and size can vary throughout the lifetime of a program.

@cindex heap
@cindex garbage collector
@cindex ML
Such memory allocations are placed in a system memory area called the
@emph{heap}, which is allocated per process on some systems, but on others may
be allocated directly from the system in scattered blocks.  Unlike memory
allocated on the stack, memory allocated on the heap is not freed when a
function or scope is exited and so must be explicitly freed by the programmer.
The pattern of allocations and deallocations is not guaranteed to be (and is not
really expected to be) linear and so the functions that allocate memory from the
heap must be able