freebsd-ports/devel/mprof/pkg-descr

MPROF -- memory profiler (version 3.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.
Call the program mprof 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 four makefiles, for the VAX, Sun-3, Sun-4, and
MIPS (specifically, the Decstation 3100 and 5000).  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), Sun-4 (cc) computers, and Decstation 3100 (gcc and cc).  To test
if mprof works in simple cases, type `make test'.

Mprof does not use Kyoto Common Lisp anymore.  To use mprof, all you
need is a C compiler.

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 Stuart Sechrest, Fred Douglis, Dain Samples, John
Ousterhout, Luigi Semenzato, Richard Tuck, Robert Scheifler, Mark
Eichin, Pat Stephenson, and Steven Sargent for their interest and
comments.

My special thanks to Jeffrey Hsu who did the tricky port of mprof to
the MIPS architecture.

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

1.  Add code to detect duplicate frees.
2.  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
 e-mail: zorn@boulder.colorado.edu
 phone:  303-492-4398


Differences between version 2.0 and 2.1:

1. In mpfilt.c, the variable stab_i was being incremented without
checking for an overflow.  Overflow checks were added.

2. A user discovered that a value of 5000 for ST_SIZE in mpfilt.c was
too small.  Large programs may require a larger value for ST_SIZE.


Differences between version 2.1 and 2.2:

1. mprof now runs on the Decstation 3100 (a MIPS machine).

2. A bug that prevented mprof from working in version 4.0 of the Sun
operating system was fixed.


Difference between version 2.2 and 3.0:

1. All analysis is now done in C.

2. The file mprof.c was renamed mprof_mon.c and the file mpfilt.c was
renamed mprof.c.

3. The old C-shell script ``mprof'' is not needed anymore.  The file
analysis.lsp is also not needed.  It's functionality is now provided
in the file mpgraph.c.

4. Small bugs previously reported were fixed.