mpatrol.html

debug source code under unix platform.

<br></tr></table>

<li>Contains 10 replacement C memory operation functions:

<p><table><tr align="left"><td><code>memset()</code>
<td>ANSI
<td>Fills memory with a specific byte. 
<br></tr><tr align="left"><td><code>bzero()</code>
<td>UNIX
<td>Fills memory with the zero byte. 
<br></tr><tr align="left"><td><code>memccpy()</code>
<td>UNIX
<td>Copies memory up to a specific byte. 
<br></tr><tr align="left"><td><code>memcpy()</code>
<td>ANSI
<td>Copies non-overlapping memory. 
<br></tr><tr align="left"><td><code>memmove()</code>
<td>ANSI
<td>Copies possibly-overlapping memory. 
<br></tr><tr align="left"><td><code>bcopy()</code>
<td>UNIX
<td>Copies possibly-overlapping memory. 
<br></tr><tr align="left"><td><code>memcmp()</code>
<td>ANSI
<td>Compares two blocks of memory. 
<br></tr><tr align="left"><td><code>bcmp()</code>
<td>UNIX
<td>Compares two blocks of memory. 
<br></tr><tr align="left"><td><code>memchr()</code>
<td>ANSI
<td>Searches memory for a specific byte. 
<br></tr><tr align="left"><td><code>memmem()</code>
<td>UNIX
<td>Searches memory for specific bytes.
<br></tr></table>

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

<li>Contains support for a user-defined low-memory handler function, including a
replacement for the C++ function, <code>set_new_handler()</code>.

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

<li>Contains support for automatically registering any functions whose names begin
with <code>__mp_init_</code> and <code>__mp_fini_</code> 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.

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

<li>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 <code>gdb</code>.

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

<li>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
internal functions.

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

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

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

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

<li>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 <code>dot</code> graph visualisation package.

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

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

<li>On UNIX platforms, the <code>mmap()</code> function can optionally be used to allocate
user memory instead of the <code>sbrk()</code> function, but only if the system
supports it.  If <code>mmap()</code> 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.

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

<li>All newly-allocated memory that is not allocated by the <code>calloc()</code> or
<code>recalloc()</code> 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.

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

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

<li>Supports the <code>-fcheck-memory-usage</code> option of <code>gcc</code> 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.

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

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

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

<li>The <code>alloca()</code>, <code>strdupa()</code> and <code>strndupa()</code> 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.

<li>Calls to memory operation functions (such as <code>memset()</code> or <code>memcpy()</code>)
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.

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

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

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

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

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

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

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

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

<li>An option exists to change the default alignment used for general-purpose memory
allocations.

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

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

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