ftp.uni-stuttgart.de/pub/systems/acorn//Acorn.tar/Acorn/acornet/dev/c/debug/mnemosyn.spk/!Mnemosyne/!Help

Text File | 1991-04-24 | 5KB | 113 lines

        This is a set of tools designed to help find memory leaks in
programs, and to locate memory-hogging functions. It's implemented as
a wrapper library that goes around malloc/free/etc, and an include file
that "intercepts" calls to malloc/free/etc and makes them call the
wrappers. Thus, you can get extensive memory profiling and leak
detection by just adding one #include directive at the top of your
file and recompiling/linking.

        Unlike some similar tools I've seen in the past, this makes
sure that it keeps its on-disk data current, so that if the program
is crashed or interrupted, the results still have some validity. The
on-disk data is as compacted as I could make it, to give a chance of
this being useable in debugging big memory pigs. It adds some cost
in performance and memory size (since it keeps its own in-memory
symbol tables) but since it's only a debugging tool, I think the
cost is worth the benefit. This library can also be used to track
only allocations in a single module, or set of modules, and doesn't
interfere with calls to the "real" malloc() that are made in other
library routines.

        Every effort has been made to ensure that the code is
portable and won't interfere with running code - it should just
plug in or out. The biggest hindrances are forward declarations of
malloc() [which the preprocessor gleefully turns into syntax errors
for you] and structure elements named "free". The code has been
tested under Ultrix on DEC Risc and VAX systems, and under SunOS
on a Motorola platform.  Please send patches, suggestions, etc,
to the author, who will probably not have time to do anything with
them.

Compiling and building:
        You may wish to edit the Makefile and glance at mnemconf.h,
then simply type "make". "make mtest" will build a simple test program
that will give you an idea of how things work. "make runmtest" will
run the test and do analysis on it.

Marcus J. Ranum
[e-mail]

=====

This copy which you have was hacked by Graham Toal <[e-mail]>
primarily for the archimedes, although I have also made it DOS portable.

If compiling on the Archimedes, you will get extensions which the
normal package doesn't offer.

The first is that *all* you have to do to your source is

                  #include <mnemosyn.h>

at the top after the system include files.  You don't have to call a
procedure to save the symbol table, because I use the Ansi atexit() function
to do that for you.

The most useful additions however are 'tombstones' -- markers at each end of
every array which can be checked periodically; these help detect errors
caused by writing past the end of arrays.  They don't detect gross errors;
just the more common off-by-one error where the very next location has been
accessed by accident.  (eg char *a = malloc(10); a[10] = 0;)

Also, this tombstone checking is normally done automatically for *all* areas
you have allocated (even ones you've lost all pointers to :-)), rather than
just the one you are currently freeing or reallocing.  This helps you find
these errors much earlier than you would normally.

Most of the other things I've added have to do with improved diagnostics; on
the Archimedes I can tell whether a variable is in the heap, or somewhere in
code/constant space.

The diags also include the name of the procedure which called malloc -- this
relies on poking around in the object file, so can be disabled if need be.
You have to compile -gf to make sure suitable info is stored in your object.
(if you don't, some of the names may be wrong due to the compiler optimising
code and moving it around.  If you don't want to use -gf, make sure mnemosyn
has been compiled *without* -DCALLER)

I've used the Ansi stringizing operator to pass the name of the variable in
to free() and realloc().

If you step a pointer past the value returned by malloc (eg accidentally
having moved a string past some prefix, then decided to free the string) we
can find out which malloc area you were in and tell you where it was
allocated.


These additions are very much *hacks* to Marcus Ranum's excellent code; all
bugs introduced are down to me; all credit for the original excellent design
is down to Marcus.  It was so easy to port to both the Archimedes and Dos;
portable code is normally the exception on usenet.  I've tried to maintain
that original portability as best as I can, so most of these extensions can
be ifdef'd out if they cause problems.

Thanks again to Marcus Ranum.  An excellent piece of work.  Saved me weeks
of debugging.

Graham Toal, 18/04/91
[e-mail]

PS because code errors sometimes cause mnemosyne's internal structures to
become corrupt, with the result that I can't find the information about some
malloc, I've added a parameter to the mnemalyse program which prints out a
single entry from the mnem.dat file.  Use this if you get a message such as
"(see map entry 10 in mnem.dat)"

On the Archimedes, mnemalyse is provided on an icon (!Mnemo) (onto which you
normally drop mnem.dat).  To use this extension, menu on the icon and select
"Set Options". Change "mnemosyne " to "mnemosyne 10", press return, then
drop mnem-dat on it as normal.

PPS You'll need PMoore's <utils> library.  I'll include my copy...