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.
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
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.
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 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.
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.
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.
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.
The mpatrol library can also be used with JNI applications. To do this, simply link the archive form of the thread-safe mpatrol library with your JNI application. That way you won't end up profiling the entire JVM.
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
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
MP_MALLOC() family of functions are always defined, even if
libmpatrol or libmpalloc are unavailable. It makes use of the
HAVE_MPALLOC preprocessor macros that are
controlled by the automake macro, but in other respects behaves in exactly the
same way as mpatrol.h.
 Also available on DG/UX 4.20MU05 with patch dgux_R4.20MU05.p59 and DG/UX 4.20MU06 with patch dgux_R4.20MU06.p08.