mpatrol.txt

debug source code under unix platform.

     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