FAQ FOR THE MPATROL LIBRARY


This file contains frequently asked questions about the mpatrol library and
their corresponding answers or solutions.


 1. DOCUMENTATION

 Q. I can't seem to format the TeXinfo manual for mpatrol into anything that I
    can view or print.  What am I doing wrong?

 A. You'll need to have the appropriate document formatting programs installed
    on your system before you can do this, and even then you'll also need to
    have suitable software for viewing or printing the formatted documents.  You
    can download an archive containing the latest mpatrol manual in a variety of
    formats from http://www.cbmamiga.demon.co.uk/mpatrol/ and this will also
    contain a file telling you where to get programs that can be used to view or
    print these files.  Alternatively, you can browse the latest mpatrol manual
    on-line at the same site.

 Q. I'd like to convert the mpatrol manual to a different documentation format
    but there is no support for that format in the Makefile.  How would I go
    about doing this?

 A. Since TeXinfo is intended to be converted to other documentation formats it
    should be fairly easy for you to find a tool which will convert it into your
    desired format.  I plan to also provide the mpatrol manual in DocBook format
    if and when a suitable TeXinfo to DocBook converter becomes available, but I
    won't provide preformatted versions of the mpatrol manual in any other
    format which isn't already supported.

 Q. How do I install the mpatrol manual as a GNU info file?

 A. Assuming you have the GNU info file built and copied to your system's info
    file directory, you should use the install-info command to place an entry
    for mpatrol in your system's GNU info directory file, otherwise the GNU info
    reader may not be able to locate the mpatrol entry.  You may also need to
    modify your INFOPATH environment variable if you installed the GNU info file
    in a non-standard place.

 Q. How do I install the mpatrol manual pages?

 A. This is very system-dependent, but need only be done on UNIX systems since
    they cannot be used on other platforms.  The unformatted manual pages exist
    in man/man1 and man/man3 and should be copied to your system's manual page
    directory.  If you don't have the nroff command installed on your system
    then you may also need to copy the formatted manual pages, located in
    man/cat1 and man/cat3.  You may also need to modify your MANPATH environment
    variable if you installed the manual pages in a non-standard place, and some
    systems require you to update the whatis database after installing new
    manual pages, by running makewhatis, catman or equivalent.  Note that there
    are two manual pages for mpatrol with the same name and you are likely to
    see the section 1 manual page by default.  You must explicitly specify the
    section number when using the man command in order to view the other manual
    page.


 2. LINKING

 Q. Why do I get undefined symbols when linking with the mpatrol library?

 A. This is most likely caused by the mpatrol library requiring additional
    symbols defined in an object file access library.  If mpatrol was built with
    FORMAT=FORMAT_ELF32 then you'll need to add -lelf (or equivalent) to the
    compiler command line straight after -lmpatrol.  If mpatrol was built with
    FORMAT=FORMAT_BFD then you'll need to add -lbfd -liberty (or equivalent)
    instead.  If you are using the thread-safe version of mpatrol then you may
    also need to link with the system threads library.

 Q. Why do I get duplicate definitions of symbols when linking with the mpatrol
    library?

 A. This is most likely caused by your code, or a library, providing definitions
    of malloc() and free() which conflict with those defined in the mpatrol
    library.  You'll need to disable these in order to perform a successful link
    and use the replacements in mpatrol instead.

 Q. I linked my program to a shared library version of mpatrol.  Now, when I try
    to run my program, the system complains that it cannot find the mpatrol
    library.  How do I get this to work?

 A. You need to tell the system where to find the shared library version of the
    mpatrol library, either by setting your LD_LIBRARY_PATH environment variable
    (or just PATH on Windows platforms), or by embedding the full path to the
    library into the executable when you link your program by setting the
    LD_RUN_PATH environment variable.

 Q. I linked my program to a shared library version of mpatrol.  Will future
    releases of mpatrol remain compatible with this version or will I have to
    relink my program?

 A. Backwards compatibility is not generally guaranteed, but should be preserved
    if only the bug fix part of the mpatrol version number has changed, with the
    major and minor versions staying the same.  For example, versions 1.0.3 and
    1.0.8 should be compatible, but upgrading to version 1.1.0 may require a
    relink.


 3. RUNNING

 Q. I've just linked and run my program with the mpatrol library, but the
    resulting log file doesn't contain any useful information.  Why does it not
    contain a list of all memory transactions or show any unfreed memory
    allocations?

 A. By default, the mpatrol library will only write a summary of library
    settings and statistics to the log file, and that will only occur on
    successful program termination (i.e. when exit() is called).  If this does
    not appear then it is likely that your program (or some other library
    function) called abort() due to a fatal error.  However, there are a
    multitude of different options that you can pass to the mpatrol library via
    the MPATROL_OPTIONS environment variable that will allow you to control what
    is logged and what is not.  Note that the mpatrol shell script will always
    log all calls to allocate, reallocate and free memory by default.

 Q. I am trying to use the mpatrol shell script to debug an executable file that
    was not originally compiled with the mpatrol library.  However, even though
    it runs successfully, no mpatrol log file is produced.  Why is this?

 A. First, check that you are passing the -d option to the mpatrol shell script.
    If that doesn't work then check that the executable file has been
    dynamically linked; statically linked executables cannot be forced to use
    the mpatrol library.  If it still doesn't work then it may be that the
    dynamic linker on your system doesn't recognise the LD_PRELOAD environment
    variable, in which case you can't use this feature.

 Q. I know that there's a definite heap corruption problem in my program as it
    keeps crashing in unrelated code due to pointer corruption, and when I link
    with the mpatrol library it stops crashing.  What can I do?

 A. Try as many of the relevant mpatrol run-time options as possible and make
    sure that you closely examine the mpatrol log file for warnings and errors -
    your problem may have been noticed by the mpatrol library but it may not
    have considered it a fatal error and continued execution.  If this still
    doesn't show up anything then you can probably rest assured that you have a
    memory corruption problem but you may need to use a commercial product such
    as Purify to isolate it.  If that fails then you'll just have to employ the
    traditional debugging method of single-stepping through your program in a
    debugger until something unusual or unexpected happens.

 Q. If I link my program to version 1.0 of the mpatrol library then I cannot
    interrupt it using the keyboard, which I would normally be able to do
    without using mpatrol.  Is this a bug?

 A. Not really, but it is undesirable behaviour in most cases, which is why it
    was removed in later releases of mpatrol and replaced with the SAFESIGNALS
    option.  The reason that the program could not be interrupted using the
    keyboard was that mpatrol would ignore such signals when its library code
    was being executed, otherwise user-defined signal handlers that used
    malloc() and related functions would have the capability to cause lots of
    undesirable side effects.  However, this does not normally happen, which is
    why the behaviour was moved to an option for those that needed it.

 Q. I've linked and run my program with mpatrol under UNIX and it uses a large
    amount of heap memory.  However, it crashes near the end of execution and
    then proceeds to freeze up the whole system, sometimes requiring a reboot.
    What am I doing wrong?

 A. The most common possible explanation for this is that you are running your
    program with too much access to system resources.  What is likely to be
    happening is that when your program crashes the system attempts to dump the
    entire process image to a core file for later debugging in a non-symbolic
    debugger.  If the process has a huge heap then the core file is also going
    to be huge, thus resulting in a massive file that may lead to the system
    thrashing while it attempts to write it to the disk.  Technically, the
    system has not frozen, but it is likely to take a long time to finish
    writing the file.  The best solution involves setting your program's maximum
    core file size to a reasonable limit (or just zero), and also possibly
    limiting your program's maximum data segment size as well.  These can be set
    from the shell but the exact details on how to do this differ between
    shells.

 Q. Why does my program run so slowly after I link it with the mpatrol library?

 A. Normal malloc libraries are optimised for speed but will typically fall over
    at the slightest hint of an error.  Debugging malloc libraries are written
    to provide as much debugging information as possible whilst performing a
    multitude of additional checks, which is why they may run much slower.
    However, you can control which checks are performed (and when) by using the
    MPATROL_OPTIONS environment variable.  Performance may also be lost if you
    make lots of small memory allocations rather than fewer larger allocations,
    but that is mainly due to the overhead of storing the extra tracing details
    for each memory allocation.

 Q. My program is written in C++ and is linked to the mpatrol library, but how
    do I go about demangling the C++ symbol names that are shown in the stack
    tracebacks in the resulting log file?

 A. Because there is no standard way of mangling C++ symbol names, various
    compilers and operating systems have taken different approaches to C++ name
    mangling, many of which differ significantly from the method suggested in
    The Annotated C++ Reference Manual by Margaret Ellis and Bjarne Stroustrup.
    However, most compilers come with a demangling tool which can be used in a
    command pipe to accept mangled names on its standard input file stream and
    demangle them on its standard output file stream, and so can be used to
    process the mpatrol log file.

 Q. Why does my program not stop when the mpatrol library notices an error?

 A. The library was written to give as much information as possible and so
    sometimes, when a non-fatal error is discovered, the library will write
    the error message to the log file and continue in the hope of being able
    to uncover more errors during the execution of the program.  This means
    that you should always check the number of warnings and errors given in
    the summary at the end of program execution, and then search backwards in
    the log file for WARNING or ERROR.


 4. FILES

 Q. Why is there a libmpatrol.o target in the UNIX Makefile?

 A. This is simply used to build the mpatrol library as one large object file
    for full incorporation into other libraries and was used during the
    development of mpatrol.  On UNIX platforms some linkers support the -r
    option for combining many object files into one large object file, but this
    is not universally supported, hence the reason for using the compiler
    instead.  Because all of the source files are compiled at once, there may be
    conflicts with system header files when malloc() and its related functions
    are being compiled, which is why such an object file is not built by
    default.  Note that the Amiga Makefile uses mpatrol.o and the Windows and
    Netware Makefiles use mpatrol.obj.

 Q. What are the CVS subdirectories that come with the mpatrol distribution?

 A. CVS stands for Concurrent Versions System and is a project version control
    system.  All of the source files that comprise an mpatrol release are stored
    in a central CVS repository so that previous releases can be easily
    retrieved, but the CVS system needs to have a way of determining the
    versions of currently checked-out files, hence the CVS subdirectories.  You
    shouldn't need to worry about them, so just ignore them.

 Q. What does the mupdate shell script do?

 A. This is for my use in order to automate every new release of mpatrol.  You
    should never need to run this script and it should not be installed
    anywhere on your system.  This script also uses and modifies the VERSION
    file and updates the NEWS and ChangeLog files.
