mpatrol.texi

debug source code under unix platform.

internal functions.

@item
All diagnostics and logging are sent to a file in the current directory, but
this can be overridden, including forcing the log file to be the standard output
or standard error file streams.  An environment variable specifying a default
directory in which to place log files can also be set.

@item
Options exist to log details of every memory allocation, reallocation or
deallocation when they occur.  A function exists to log the details of any
memory allocation to the mpatrol log file.

@item
Options exist to halt the program at a specific memory allocation, reallocation
or deallocation when running the program within a debugger.  These options have
no effect when running the program without a debugger.

@item
An option exists to enable memory allocation profiling, which forces a summary
of all memory allocation statistics to be written to a specified file for later
use by a profiling command.  The profiling file can also be written at a
specified frequency.  An environment variable specifying a default directory in
which to place profiling output files can also be set.

@item
A profiling command is provided which reads a profiling output file produced by
the mpatrol library and displays a set of tables based on 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.

@item
An option exists to enable memory allocation tracing, which forces certain
details for every memory allocation event to be written to a specified file for
later use by a tracing command.  The tracing file is written in a concise
encoded form so as to keep the size of the file down.  An environment variable
specifying a default directory in which to place tracing output files can also
be set.

@cindex trace-driven simulation
@cindex simulation, trace-driven
@item
A tracing command is provided which reads a tracing output file produced by the
mpatrol library and displays the memory allocation events in tabular or
graphical form.  It also displays any relevant statistics that could be
calculated, and has options to write out the trace in HATF format or write out
a trace-driven memory allocation simulation program as C source code.

@item
On UNIX platforms, the @code{mmap()} function can optionally be used to allocate
user memory instead of the @code{sbrk()} function, but only if the system
supports it.  If @code{mmap()} is supported then internal mpatrol library memory
is normally allocated with this function in order to segregate it from user
memory but this behaviour can be swapped around.

@item
On non-UNIX platforms where the mpatrol library overrides @code{malloc()}
without requiring the inclusion of @file{mpatrol.h}, versions of the UNIX
functions @code{brk()} and @code{sbrk()} are provided for compatibility with
certain libraries.  These should @emph{not} be called by user code as they have
only limited functionality.

@item
All newly-allocated memory that is not allocated by the @code{calloc()} or
@code{recalloc()} functions will be pre-filled with a non-zero value in order to
catch out programs that wrongly assume that all newly-allocated memory is
zeroed.  This value can be modified at run-time.

@item
Can automatically check to see if there have been any illegal writes to bytes
located just before and after every memory allocation through the use of
overflow buffers.  The size of such overflow buffers and the value to pre-fill
them with can be modified at run-time.  The checks will be performed before
every memory allocation call to ensure that nothing has overwritten the
overflow buffers, but a function is also provided to perform additional checks
under the programmer's control and an option exists to specify a range and
frequency in which checks will be performed.

@item
On systems that support them, watch point areas can be used instead of overflow
buffers so that every read and write to memory is checked to ensure that it is
not within an overflow buffer.

@item
Supports the @option{-fcheck-memory-usage} option of @command{gcc} to check all
heap memory accesses in programs that were compiled with that option.  Currently
this only supports checking that memory accesses do not overflow heap
allocations or access free memory, rather than keeping records of individual
memory accesses that GNU Checker does.

@item
Can automatically check to see if there have been any illegal writes to free
memory blocks.  The value to pre-fill free memory blocks with can be modified
at run-time.  The check will be performed before every memory allocation call
to ensure that nothing has overwritten the free memory block, but a function is
also provided to perform additional checks under the programmer's control and
an option exists to specify a range in which checks will be performed.

@item
On systems that support memory protection, every memory allocation can
optionally be allocated at least one page of memory.  That way, any free memory
blocks can be made read and write protected so that nothing can access free
memory on the heap.  An option is provided to specify whether all memory
allocations should be allocated at the start or at the end of such pages, and
the bytes left over within the pages become overflow buffers.

@item
All freed memory allocations can optionally be prevented from being returned to
the free memory pool.  This is useful for detecting if use is being made of
freed memory just after a memory allocation has been freed.  The contents of
the memory allocation can either be preserved or can be pre-filled with a value
in order to detect illegal writes to the freed memory allocation.  In addition,
only a specified number of recently-freed memory allocations can be prevented
from being returned to the free memory pool.  Any older freed memory allocations
will then eventually be reused.

@item
The @code{alloca()}, @code{strdupa()} and @code{strndupa()} functions are
implemented so that the temporary stack-based allocations that they would
normally make are now temporary heap-based allocations that can be traced by
mpatrol.  Such allocations will be implicitly freed when the function that
allocated them returns, but a function also exists to explicitly free them as
well.

@item
Calls to memory operation functions (such as @code{memset()} or @code{memcpy()})
have their arguments checked to ensure that they do not pass null pointers or
attempt to read or write memory straddling the boundary of a previously
allocated memory block, although an option exists to turn such an error into a
warning so that the operation can still be performed.  Tracing from all such
functions can also optionally be written to the log file.

@item
The internal data structures used by the library are kept separate from the
rest of the memory allocations.  On systems that support memory protection, all
of these internal data structures will be write-protected in order to prevent
corruption by the calling program.  This feature can be overridden at run-time
as it can slow the program down.

@cindex signals
@item
Certain signals can be saved and restored on entry to each library function and
@code{errno} is set to @code{ENOMEM} if memory cannot be allocated, except for
the ANSI C++ operators which throw the @code{std::bad_alloc} exception instead.

@item
On systems that support memory protection, the library attempts to detect any
illegal memory accesses and display as much information as it can obtain about
the address in question and where the illegal memory access occurred.

@item
A call stack traceback from any function performing a memory allocation is
stored if the library supports this feature on the system it is being run on.
This information can then be displayed when information about a specific memory
allocation is required.  Many different call stack traceback implementations are
provided for different platforms.  A function is also provided to write the
current call stack to the mpatrol log file.

@item
Symbol table details from executable files and shared libraries are
automatically read on systems that support this feature in order to make the
call stack tracebacks more meaningful.  An option also exists to display a
complete list of the symbols that were read by the library at program
termination.  A function is also provided to return symbolic information about
any code address.

@item
Compiler-generated line number tables from any debugging sections that exist
in executable files and shared libraries can also be used by the mpatrol library
in order to provide more meaningful information in call stack tracebacks.  An
external command is also provided to make use of a debugger to get such
information if one is available.

@item
If the library is unable to automatically determine a program's executable
filename to read symbols from then an option exists to specify the full path to
the program's executable file.

@item
Options are provided to edit and list a source file at a specific line number
when a warning or error occurs due to that source line.  An external command
which provides this functionality outwith the mpatrol library is included, and
functions are provided to do this from within user code.

@item
An option exists to change the default alignment used for general-purpose memory
allocations.

@item
Contains support for a user-defined limit to available memory which can be
useful for stress-testing a program in simulated low memory conditions.

@item
Contains a feature to randomly fail a specific frequency of memory allocations
which can be useful for stress-testing error recovery code in a program.

@item
An option exists to display a complete memory map of the heap at program
termination.  A function to do this is also available to call at any point
during program execution.

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

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

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

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

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

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

@item
Memory allocations can be @emph{marked} 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.

@item
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[]} is not freed with
@code{free()} for example.

@item
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 @command{gcc}, the function name will also be stored and the
thread identifier will be stored if using the thread-safe library.

@item
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 @command{gcc}), 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} preprocessor macro, which also
disables the effect of calling any mpatrol library function.

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

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

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

@item
An automake macro is provided to ease the integration of mpatrol into a new or
existing project.

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

@item