mpatrol.txt

debug source code under unix platform.

     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.

3 Installation
**************

   The mpatrol library was initially developed on an Amiga 4000/040
running AmigaOS 3.1.  I then installed Red Hat Linux 5.1 on my Amiga
and added support for Linux/m68k.  I've now just recently purchased a
Dell Inspiron 7500 Notebook PC and put my Amiga in retirement, so
development will now continue on Red Hat Linux 6.2 and above on the
Intel platform.  I've tried my best to make it as easy as possible to
build and install mpatrol on any system, but it isn't likely to run
smoothly for everybody.  However, there shouldn't be any major problems
if you perform the following steps.

   Note that if you want to check the integrity of the files that came
with the mpatrol distribution you can use the `CHECKSUMS' file in the
`mpatrol' base directory.  You must have the `md5sum' command installed
on your system in order to make use of this file.

   If you wish to use GNU autoconf, automake and libtool to build and
install mpatrol you may do so by entering the `pkg/auto' directory and
typing `./setup'.  This will construct the directory structure that is
required by these tools and will also create a `configure' script.
Please see the `INSTALL' file in that directory for information on how
to proceed.  Note that you can clean up the `pkg/auto' directory by
typing `make distclean' (if the `configure' script has already been
run) followed by `./cleanup'.

   For a manual installation, perform the following steps.

  1. Go into the `build' directory and then into the appropriate
     subdirectory for your system.

  2. Edit the `Makefile' in that directory and check that it is using
     the appropriate compiler and build tools.  The `CC' macro
     specifies the compiler(1), the `AR' macro specifies the tool used
     to build the archive library and the `LD' macro specifies the tool
     to build the shared library.  The `CFLAGS' macro specifies
     compiler options that are always to be used, the `OFLAGS' macro
     specifies optimisation options for the compiler, the `SFLAGS' macro
     specifies options to be passed to the compiler when building a
     shared library and the `TFLAGS' macro specifies options to be
     passed to the compiler when building a thread-safe library.  You
     may also need to change the library names and library build
     commands on different systems.

     Note that the generic UNIX `Makefile' contains a macro called
     `GUISUP' which is set to `false' by default.  If it is set to
     `true' then the `mptrace' command will be built with GUI support
     enabled.  However, your system must contain the correct header
     files and libraries in order to support this.

  3. Use the `make' command (or equivalent) to build the mpatrol
     library in archive form.  The `all' target builds all possible
     combinations of the mpatrol library for your system.  The `clean'
     target removes all relevant object files from the current
     directory, while the `clobber' target also removes all libraries
     that have been built from the current directory.  On some UNIX
     platforms, the `lint' target will build a `lint' library for the
     mpatrol library.

  4. If the mpatrol library is to be built with support for Parasoft
     Inuse then the `MP_INUSE_SUPPORT' preprocessor macro must be
     defined in the `CFLAGS' portion of the `Makefile' before building.
     This will ensure that Inuse will be notified of every memory
     allocation, reallocation and deallocation, but the Insure++
     runtime library will also have to be linked in with any program
     that uses mpatrol.

  5. Copy all of the libraries that have been built into your local
     library directory.  If there were symbolic links created in the
     `build' directory then these should be recreated in the local
     library directory rather than simply copying them.  You may need
     to run a command such as `ldconfig' in order for the system to
     recognise the newly-installed libraries, and you may also need to
     add the filename of the directory containing the newly-installed
     libraries to an environment variable such as `LD_LIBRARY_PATH' if
     you installed the libraries in a non-standard location.

  6. Copy the `mpatrol', `mprof', `mptrace' and `mleak' programs that
     have been built into your local bin directory.  You may also wish
     to copy the `mpsym', `mpedit' and `hexwords' commands to your
     local bin directory as well if your system supports Bourne shell
     scripts.

  7. Go up two directory levels into the `src' directory and copy the
     `mpatrol.h', `mpalloc.h' and `mpdebug.h' header files into your
     local include directory.

  8. Go up one directory level into the `tools' directory and copy all
     of the header files into the `mpatrol' subdirectory (which you'll
     need to create) in your local include directory.

  9. On UNIX platforms, go up one directory level into the `man'
     directory and copy the `man1' and `man3' subdirectories to your
     local man directory.  Unfortunately, the location for manual pages
     varies from system to system so you may or may not also be able to
     copy the `cat1' and `cat3' subdirectories as well.  The `man*'
     subdirectories contain the unformatted manual pages while the
     `cat*' subdirectories contain the formatted manual pages.

 10. Go up one directory level into the `doc' directory and examine the
     files located there.  The `mpatrol.texi' file contains the TeXinfo
     source for this manual and can be translated into a wide variety
     of documentation formats.  The `refcard.tex' file contains the
     LaTeX source for the quick reference card and can be translated
     into formats suitable for printing onto a few pages.  There should
     already be translated files in the `doc' directory, but if not you
     will have to generate them yourself using the `Makefile' provided.
     You can then install or print these documents.

     The mpatrol library source code can also be formatted for a