
MPROF -- memory profiler (version 2.0)

To use mprof, you must link the library libc_mp.a (found in the mprof
directory) into your application (this library is the C library with
the definitions of malloc and free replaced).  Profiling starts
automatically when malloc is first called.  Profile data is written to
the file "mprof.data".  There are several functions that users can
call to change the name of the output file, etc.  See the man page in
mprof.man.

Simply by linking in the new malloc and executing your application, a
file called ``mprof.data'' will be created in the current directory.
This is the data file that mprof uses to build its dynamic call graph.
To look at the output of mprof, first edit the script `mprof' in the
mprof directory.  Replace the mproot variable with the correct
pathname of the mprof directory (the directory in which this
``README'' file is located).  Then place the mprof directory in your
search path, and call mprof in your application directory with the
following arguments:

mprof [ options ] [ executable-file (a.out) ] [ data-file (mprof.data) ]

The output contains four tables, the fields of which are described in
the man page in mprof.man.  Further documentation is available in a
paper which describes the implementation of mprof (published in the
1988 summer USENIX conference) .  The LaTeX source of that paper is
located in mprof.tex.  The printable DVI file is located in mprof.dvi.

There are currently three makefiles, for the VAX, Sun-3, and Sun-4.
To remake mprof, copy the appropriate file to `Makefile'.  If you need
to recompile mprof for any reason, type ``make all'' in this
directory.  To remove .o files, type ``make clean'' in this directory.
mprof has been tested on VAX (4.3 BSD and Ultrix using gcc and cc),
SUN-3 (gcc and cc), and Sun-4 (cc) computers.  To test if mprof works
in simple cases, type `make test'.

mprof currently uses kcl (Kyoto Common Lisp) to do output.  If your
computer has kcl and it's in your search path (usually at
/usr/local/kcl or /usr/public/kcl), everything will work correctly.
If your computer doesn't have kcl, any other Common Lisp should work.
To use another Common Lisp, just modify Makefile and mprof to use your
version of Common Lisp.

The current incarnation of mprof does not handle calls to Sun calls to
valloc or memalign correctly.  The calls will be profiled, but if your
program calls valloc or memalign and tries to later free that memory,
mprof will cause it to core dump.  On the VAX, memory allocated by
valloc cannot be freed, and so valloc can be profiled correctly on the
VAX.  A version of malloc.c is provided with mprof.  If this version
is not compatible with the version used on your machine, you may need
to replace this file.  If you have problems like this, please let me
know so I can keep a record of the bugs encountered.

My thanks to Fred Douglis, Dain Samples, John Ousterhout, Luigi
Semenzato, Richard Tuck, Robert Scheifler, Mark Eichin and Pat
Stephenson for their interest and comments.

In the future (although the exact date is uncertain) I plan to make
the following improvements to mprof:

1.  Eliminate the code written in Common Lisp and provide a C only
    version.
2.  Add code to detect duplicate frees.
3.  Fix up the type determination code in mpfilt (see BUGS section in
    the man page for mprof).
 
If you have any questions or comments, please feel free to contact me.

-Ben Zorn (zorn@ernie.berkeley.edu)
 415-642-8290

