mpatrol.txt

debug source code under unix platform.

     printed manual for later perusal.  The `source' target in the
     `Makefile' within the `doc' directory can be used to build the
     source code documentation in DVI, postscript and PDF formats, but
     be prepared for a large number of pages!

     If you are not installing on a system that supports UNIX manual
     pages then you should also check in the `man' directory to ensure
     that there are alternative formats for the mpatrol manual pages
     that you can install.  If not, you will have to generate them
     yourself using the `Makefile' provided.

   Alternatively, the `pkg' directory contains files that can be used to
automatically generate a _package_ in a specific format suitable for
installation on a system.  Four package formats (PKG, SD/UX, RPM and
Debian) and three archive formats are currently supported (generic tape
archive, LhA and ZIP).

   The first package format is generally used on UNIX SVR4 systems,
while the second is used on HP/UX systems.  The RPM and Debian package
formats were introduced by Red Hat and Debian respectively for use in
their Linux distributions.

   The generic tape archive can be used as a distribution for UNIX
systems where no package format is supported, but it does not contain
information on how to install the files on the system once they have
been extracted from the distribution.  The LhA and ZIP formats are also
roughly the same, but the LhA format is intended for Amiga systems and
is used for Aminet distributions, while the ZIP format is intended for
Windows systems and is used for WinSite distributions.

   You should really know what you are doing before you attempt to
build a package, and you should also be aware that some of the package
files may need to be modified before you begin.

   In addition, a Linux Software Map index file exists in the `pkg/lsm'
directory.

   Note that the `extra' directory that comes with the mpatrol
distribution contains several prototype configuration files for certain
third-party programs.  These files should be examined so that you can
decide whether to integrate their contents into your existing
configuration files.  The purpose of each file is described in the
relevant sections of this manual.

   ---------- Footnotes ----------

   (1) On many systems this actually a C++ compiler by default, and
should be a C++ compiler if you wish to use the C++ operators.

4 Integration
*************

   This section describes how to go about adding or removing the
mpatrol library from your code.  There are several levels for each
category so it is worth reading about each before proceeding.

4.1 Adding mpatrol
==================

   The following steps should allow you to easily integrate the mpatrol
library into an existing application, although some of them may not be
available to do on many platforms.  They are listed in the order of
number of changes required to modify existing code -- the last step
will require a complete recompilation of all your code.

  1. This step is currently only available on DYNIX/ptx, FreeBSD, IRIX,
     Linux, NetBSD, OpenBSD, Solaris and Tru64 platforms and on DG/UX
     4.20MU07(1) or later platforms with the `LD_PRELOAD' feature.

     If your program or application has been dynamically linked with
     the system C library (`libc.so') or an alternative malloc shared
     library then you can use the `--dynamic' option to the `mpatrol'
     command to override the default definitions of `malloc()', etc. at
     run-time without having to relink your program.  If your program
     is multithreaded then you must also add the `--threads' option to
     pick up the multithreaded shared libraries instead.

     For example, if your program's executable file is called
     `testprog' and it accepts an option specifying an input file, you
     can force the system's dynamic linker to use mpatrol's versions of
     `malloc()', etc. instead of the default versions by typing:

          mpatrol --dynamic ./testprog -i file

     The resulting log file should be called `mpatrol.<procid>.log' by
     default (where PROCID is the current process id), but if no such
     file exists after running the `mpatrol' command then it will not
     be possible to force the run-time linking of mpatrol functions to
     your program and you will have to proceed to the next step.  Note
     that the `mpatrol' command overrides any previous setting of the
     `MPATROL_OPTIONS' environment variable.

  2. This step is currently only available on UNIX and Windows
     platforms (and AmigaOS when using `gcc').

     You should be able to link in the mpatrol library when linking
     your program without having to recompile any of your object files
     or libraries, but this will only be worthwhile on systems where
     stack tracebacks are supported, otherwise you should proceed to
     the next step since there will not be enough information for you
     to tell where the calls to dynamic memory allocation functions took
     place.

     Information on how to link the mpatrol library to an application
     is given at the start of the examples (*note Examples::), but you
     should note that if your program does not directly call any of the
     functions in the mpatrol library then it will not be linked in and
     you will not see a log file being generated when you run it.  You
     can force the linking of the mpatrol library by causing `malloc()'
     to be undefined on the link line, usually through the use of the
     `-u' linker option.

     If your program is multithreaded then you must use the thread-safe
     version of the mpatrol library and possibly also link in the
     system threads library as well.  Not doing this will usually
     result in your program failing somewhere in the mpatrol library
     code.

  3. All of the following steps will require you to recompile some or
     all of your code so that your code calls dynamic memory allocation
     functions from the mpatrol library rather than the system C
     library.

     This first step is only available when using `gcc'.

     You can make use of the `gcc' option `-fcheck-memory-usage' which
     instructs the compiler to place calls to error-checking functions
     before each access to memory.  This can result in a dramatic
     slowdown of your code so you may wish to limit the use of this
     option to a few source files, but it does provide a very thorough
     method of ensuring that you do not access memory beyond the bounds
     of a memory allocation or attempt to access free memory.  However,
     be aware that the checks are only placed in the bodies of
     functions that have been compiled with this option and are missing
     from all functions that have not.  You must link in the mpatrol
     library when using this option, otherwise you will get linker
     errors.

     The `-fcheck-memory-usage' option was added to `gcc' to support
     GNU Checker, which can be considered to be the run-time system for
     this option.  GNU Checker also includes the ability to detect
     reads from uninitialised memory, something that mpatrol does not
     currently support, and deals with stack objects as well.  GNU
     Checker cannot be used in conjunction with mpatrol.

  4. For this step, if you have a rough idea of where the function
     calls lie that you would like to trace or test, you need only
     recompile the relevant source files.  You should modify these
     source files to include the `mpatrol.h' header file before any
     calls to dynamic memory allocation or memory operation functions.

     However, you should take particular care to ensure that all calls
     to memory allocation functions in the mpatrol library will be
     matched by calls to memory reallocation or deallocation functions
     in the mpatrol library, since if they are unmatched then the log
     file will either fill up with errors complaining about trying to
     free unknown allocations, or warnings about unfreed memory
     allocations at the end of execution.

  5. This step requires you to recompile all of your source files to
     include the `mpatrol.h' header file.  Obviously, this will take
     the longest amount of time to integrate, but need not require you
     to change any source files if the compiler you are using has a
     command line option to include a specific header file before any
     source files.

     For example, `gcc' comes with a `-include' option which has this
     feature, so if you had to recompile a source file called `test.c'
     then the following command would allow you to include `mpatrol.h'
     without having to modify the source file:

          gcc -include /usr/local/include/mpatrol.h -c test.c

   In all cases, it will be desirable to compile your source files with
compiler-generated debugging information since that may be able to be
used by the `USEDEBUG' option or the `mpsym' command.  In addition, more
symbolic information will be available if the executable files have not
had their symbol tables stripped from them, although mpatrol can also
fall back to using the dynamic symbol table from dynamically linked
executable files.

   Note that an automake macro is now provided to allow you to
integrate mpatrol into a new or existing project that uses the GNU
autoconf and automake tools.  It is located in `extra/mpatrol.m4',
which should be copied to the directory containing all of the local
autoconf and automake macros on your system, usually
`/usr/local/share/aclocal'.  The automake macro it defines is called
`AM_WITH_MPATROL', which should be added to the libraries section in
the `configure.in' file for your project.  It takes one optional
parameter specifying whether mpatrol should be included in the project
(`yes') or not (`no').  This can also be specified as `threads' if you
wish to use the threadsafe version of the mpatrol library.  You can
override the value of the optional parameter with the `--with-mpatrol'
option to the resulting `configure' shell script.

   If you are using the `AM_WITH_MPATROL' automake macro then you may
wish to use the `mpdebug.h' header file instead of `mpatrol.h'.  This
ensures that the `MP_MALLOC()' family of functions are always defined,
even if libmpatrol or libmpalloc are unavailable.  It makes use of the
`HAVE_MPATROL' and `HAVE_MPALLOC' preprocessor macros that are
controlled by the automake macro, but in other respects behaves in
exactly the same way as `mpatrol.h'.

   ---------- Footnotes ----------

   (1) Also available on DG/UX 4.20MU05 with patch dgux_R4.20MU05.p59
and DG/UX 4.20MU06 with patch dgux_R4.20MU06.p08.

4.2 Removing mpatrol
====================

   Once you have ironed out all of the problems in your code with the
help of the mpatrol library, there will come a time where you wish to
build your program without any of its debugging features, either to
improve the speed that it runs at, or perhaps even for a release.
Choose one of the following steps to help you remove the mpatrol
library from your program (you only need to perform them if you linked
your program with the mpatrol library).

  1. The quickest way to remove the mpatrol library from your
     application is to link with libmpalloc instead of libmpatrol.
     This contains replacements for all of the mpatrol library
     functions, either implementing memory allocation or memory
     operation functions with the system C library, or doing nothing in
     the functions which perform debugging, profiling or tracing.  This
     method is a very quick way to remove the mpatrol library but will
     not result in very efficient code.

  2. The next option is to recompile all of the source files which
     include the `mpatrol.h' header file, but this time define the
     `NDEBUG' preprocessor macro.  This automatically disables the
     redefinition of `malloc()', etc. and prevents calls being made to
     any mpatrol library functions.  Obviously, this option is the most
     time-consuming of the two, but will result in the complete removal
     of all references to the mpatrol library.

  3. The final option is to guard all of the mpatrol-specific code in
     your program with a preprocessor macro, possibly called
     `HAVE_MPATROL', and then recompiling all of your source code with
     this macro undefined.  This is the best option but relies on you
     having originally made these changes when you first started
     integrating the mpatrol library into your program.

   Note that if you used the `AM_WITH_MPATROL' automake macro as
detailed in the previous section to build your application then you
should perform a clean recompilation using the `--without-mpatrol'
option to the `configure' shell script in order to completely remove
the mpatrol library.

   Note also that if you used the `-fcheck-memory-usage' option of the
GNU compiler to check all memory accesses then you must recompile