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(2) 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 (see section 16. 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'.