2 Features

An overall list of features contained in the mpatrol library is given below. This is not intended to be exhaustive since the best way to see what the library does is to read the documentation and try it out.

• Written for 32-bit and 64-bit UNIX, AmigaOS, Windows and Netware platforms. Contains direct support for (and takes advantage of most of the features of) AIX, DG/UX, DRS/NX, DYNIX/ptx, FreeBSD, HP/UX, Interix, IRIX, Linux, LynxOS, NetBSD, OpenBSD, SINIX, Solaris, SunOS, Tru64 and UnixWare. Also contains target-specific code to take advantage of Alpha, Intel 80x86, Motorola 680x0 and 88xx0, MIPS, HP PA/RISC, IBM RS/6000, PowerPC and SPARC processors.
• Has the ability to read symbols from executable files and shared libraries in the a.out, COFF, XCOFF, ELF32, ELF64 and Windows Portable Executable file formats, and if the GNU BFD library is available then the mpatrol library can read symbols from all of the file formats that it has support for as well. Can also liase with AIX, BSD-based, HP/UX, Interix, IRIX, OSF, SVR4-based and Windows dynamic linkers in order to find out information about shared libraries.
• Can be built to allocate memory from a fixed-sized static array rather than using heap memory from the system.

• Can be built as archive, shared and/or thread-safe libraries on systems that support them, or even as one large object file. A lint library can also be built from the mpatrol library on UNIX platforms.
• A release version of the mpatrol library is provided, which has the same functional interface, but does not contain any of mpatrol's debugging, tracing or profiling features. It is intended to be used to quickly remove the mpatrol library.
• Details of memory allocations and free memory are stored internally as a tree structure for speed and also to allow the best fit allocation algorithm to be used. This also enables the library to perform intelligent resizing of memory allocations and can be used to quickly determine if an address has been allocated on the heap.
• Contains 19 replacement C dynamic memory allocation functions:

  malloc()	ANSI	Allocates memory.
  calloc()	ANSI	Allocates zero-filled memory.
  memalign()	UNIX	Allocates memory with a specified alignment.
  valloc()	UNIX	Allocates page-aligned memory.
  pvalloc()	UNIX	Allocates a number of pages.
  alloca()	old	Allocates temporary memory.
  strdup()	UNIX	Duplicates a string.
  strndup()	old	Duplicates a string with a maximum length.
  strsave()	old	Duplicates a string.
  strnsave()	old	Duplicates a string with a maximum length.
  strdupa()	old	Duplicates a string.
  strndupa()	old	Duplicates a string with a maximum length.
  realloc()	ANSI	Resizes memory.
  reallocf()	BSD	Resizes memory and frees on failure.
  recalloc()	old	Resizes memory allocated by calloc().
  expand()	old	Resizes memory but does not relocate it.
  free()	ANSI	Frees memory.
  cfree()	old	Frees memory allocated by calloc().
  dealloca()	new	Explicitly frees temporary memory.

• Contains 5 replacement C dynamic memory extension functions:

  xmalloc()	Allocates memory without failure.
  xcalloc()	Allocates zero-filled memory without failure.
  xstrdup()	Duplicates a string without failure.
  xrealloc()	Resizes memory without failure.
  xfree()	Frees memory.

• Contains 6 replacement C dynamic memory alternative functions:

  MP_MALLOC()	Allocates memory without failure.
  MP_CALLOC()	Allocates zero-filled memory without failure.
  MP_STRDUP()	Duplicates a string without failure.
  MP_REALLOC()	Resizes memory without failure.
  MP_FREE()	Frees memory.
  MP_FAILURE()	Sets the allocation failure handler.

• Contains 4 replacement C++ dynamic memory allocation operators (in both throw and nothrow forms):

  operator new	Allocates memory.
  operator new[]	Allocates memory for an array.
  operator delete	Frees memory.
  operator delete[]	Frees memory allocated by operator new[].

• Contains 10 replacement C memory operation functions:

  memset()	ANSI	Fills memory with a specific byte.
  bzero()	UNIX	Fills memory with the zero byte.
  memccpy()	UNIX	Copies memory up to a specific byte.
  memcpy()	ANSI	Copies non-overlapping memory.
  memmove()	ANSI	Copies possibly-overlapping memory.
  bcopy()	UNIX	Copies possibly-overlapping memory.
  memcmp()	ANSI	Compares two blocks of memory.
  bcmp()	UNIX	Compares two blocks of memory.
  memchr()	ANSI	Searches memory for a specific byte.
  memmem()	UNIX	Searches memory for specific bytes.

• 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.
• Contains support for a user-defined low-memory handler function, including a replacement for the C++ function, set_new_handler().
• 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.
• Contains support for automatically registering any functions whose names begin with `__mp_init_' and `__mp_fini_' 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.
• Contains support for user-defined prologue and epilogue callback functions, which get called before and after every memory allocation, reallocation or deallocation.
• 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 gdb.
• 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.
• 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.
• 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.
• 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.
• 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.
• 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.
• 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 dot graph visualisation package.
• 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.

• 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.
• On UNIX platforms, the mmap() function can optionally be used to allocate user memory instead of the sbrk() function, but only if the system supports it. If 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.
• On non-UNIX platforms where the mpatrol library overrides malloc() without requiring the inclusion of mpatrol.h, versions of the UNIX functions brk() and sbrk() are provided for compatibility with certain libraries. These should not be called by user code as they have only limited functionality.
• All newly-allocated memory that is not allocated by the calloc() or 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.
• 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.
• 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.
• Supports the -fcheck-memory-usage option of 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.
• 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.
• 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.
• 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.
• The alloca(), strdupa() and 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.
• Calls to memory operation functions (such as memset() or 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.
• 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.

• Certain signals can be saved and restored on entry to each library function and errno is set to ENOMEM if memory cannot be allocated, except for the ANSI C++ operators which throw the std::bad_alloc exception instead.
• 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.
• 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.
• 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.
• 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.
• 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.
• 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.
• An option exists to change the default alignment used for general-purpose memory allocations.
• Contains support for a user-defined limit to available memory which can be useful for stress-testing a program in simulated low memory conditions.
• 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.
• 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.
• 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.
• Functions are provided to iterate across all of the current heap allocations and call a user-defined callback function for each one they find.
• 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.
• Functions are provided to write user-defined information directly to the mpatrol log file, as well as hexadecimal memory dumps of any memory location.
• 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.
• 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.
• Memory allocations can be 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.
• 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 operator new[] is not freed with free() for example.
• 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 gcc, the function name will also be stored and the thread identifier will be stored if using the thread-safe library.
• 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 gcc), since the library automatically redefines the default system memory allocation functions. All redefinitions in the header can also be disabled by defining the NDEBUG preprocessor macro, which also disables the effect of calling any mpatrol library function.
• 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.
• 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++.
• 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.
• An automake macro is provided to ease the integration of mpatrol into a new or existing project.
• 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.
• 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.

• A small test suite is provided in order to test basic features.
• 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.