mprof(1)mprof(1)NAMEmprof - display dynamic memory allocation data
SYNTAXmprof [ options ] [ a.out [ mprof.data ] ]
void set_mprof_autosave(count)
int count;
void mprof_stop()
void mprof_restart(filename)
char *filename;
DESCRIPTION
The mprof command produces four tables that summarize the memory allo‐
cation behavior of C programs, similar in style to the gprof command.
The arguments to mprof are the executable image (a.out default) and the
profile data file (mprof.data default). The mprof.data file is gener‐
ated by linking a special version malloc into the executing image. This
new version, found in the library libc_mp.a must be linked in at the
end of the command that creates the executable image. For example:
cc -g -o test main.o sub1.o sub2.o libc_mp.a
Users' programs can contain additional calls to customize the user
interface to mprof. The function set_mprof_autosave allows users to
save the profile data periodically. The count parameter specifies to
save after that number of allocations. A value of 10,000 or 100,000 is
typical for the count parameter for long running programs. A value of
0 (the default) causes the the profile data to be written only when the
program exits. The function mprof_stop causes memory profiling to be
discontinued and the profile data to be written to the output file.
The function mprof_restart restarts profiling. The filename parameter
to mprof_restart specifies the name of the file to write the profile
data to.
The output of mprof consists of four tables, the fields of which are
described in detail below. The first table breaks down the memory
allocation of the program by the number of bytes requested. For each
byte size the number of allocations and frees is listed along with the
program structure types that correspond to that byte size.
The second table lists partial call chains over which memory was allo‐
cated and never freed (call chains resulting in memory leaks). The ta‐
ble shows how much memory was allocated by each chain and how much each
chain contributed to the total memory leakage.
The third table lists the functions in which allocation occurred
directly (i.e., called malloc), indicates how much memory was allo‐
cated, shows how much of that was not later freed, breaks down alloca‐
tion roughly by size, and shows how many times each function was
called.
The fourth table contains the subgraph of the program's dynamic call
graph in which allocation occurred. This table allows programmers to
identify what functions were indirectly responsible for memory alloca‐
tion.
The following options are available:
-verbose
Every bin in which memory was allocated is printed; the call
chain for every memory leak is shown.
-normal
Only bins that contributed a reasonable fraction to the total
allocation are printed; call chains for leaks contributing more
than 0.5% to the total are shown. This is the default verbosity
setting.
-terse Only bins that contributed a significant fraction to the total
allocation are printed. Call chains contributing more than 1%
to the total leakage are shown.
-leaktable
Print out the memory leak table without printing out call site
offsets. This is the default.
-noleaktable
Do not print out the memory leak table.
-offsets
Print out the memory leak table and distinguish different call
sites within a function by indicating the offset in the function
as part of the path. This is useful to identify a particular
call site in a function with many call sites that allocate mem‐
ory.
FIELDS IN THE OUTPUT
Often in the tables, percentages are presented in two column fields.
In such a field, a blank indicates 0%, a dot indicates less than 1%,
and two stars indicate 100%.
When data is broken down by size categories, the categories mean the
following:
s = small x <= 32 bytes
m = medium 32 < x <= 256 bytes
l = large 256 < x <= 2048 bytes
x = extra large x > 2048 bytes
where x is the exact size of the object being allocated by a call to
malloc. When data is broken into categories, percentages are always
given in a two column format. Throughout this document, we refer to
such a listing as a ``breakdown''.
TABLE 1: ALLOCATION BINS
The memory allocation is broken down by the sizes of objects requested
and freed.
size The size in bytes of the object allocated or freed.
allocs The number of calls to malloc requesting allocation of
this size.
bytes (%) The total number of bytes allocated to objects of this
size. The percent indicates the percent of the total
bytes allocated.
frees The number of times objects of this size were freed.
kept (%) The number of bytes of objects of this size that were
never freed. The percent indicates what fraction of
unfreed bytes were allocated to objects of this size.
types A list of the program names of structure types or type‐
defs that define objects of this size.
TABLE 2: MEMORY LEAKS
The memory leak table lists the partial call chains which allocated
memory that was never freed. At most five functions in the call chain
are listed.
kept bytes (%)
The number of bytes allocated on this partial call chain
and not subsequently freed. The table is sorted by
decreasing values in this field. The percent indicates
the percent of total bytes not freed.
allocs The number of allocations that occurred on this partial
call chain.
bytes (%) The number of bytes allocated on this partial call chain.
The percent indicates the percent of the total bytes
allocated and never freed.
frees The number of frees that occurred on this partial call
chain. If no objects were freed this and the following
field are ommitted.
bytes (%) The number of bytes freed on this partial call chain.
This field is omitted if no bytes were freed.
path The partial call chain. Call chains starting with "..."
indicate that more callers were present, but were ommit‐
ted from the listing. Call chains consist of function
names (and possible call site offsets) separated by ">".
Call site offsets are indicated by a +n following the
function name, where n is the distance in bytes of the
call site from the start of the function. Call site off‐
sets are printed using the -offset option.
TABLE 3: DIRECT ALLOCATION
The <TOTAL> row of the direct allocation listing contains a summary of
all the functions where such a summary makes sense.
% mem Percentage of the total memory allocated that was allo‐
cated by this function.
bytes The total number of bytes allocated by this function.
% mem(size) Size breakdown of the memory allocated by this function
as a percentage of the total memory allocated by the pro‐
gram. For example, if the values for function MAIN are
s=5, m=20, l=4, x=0, then direct calls to MALLOC from
MAIN account for 5+20+4+0 = 29% of the total memory allo‐
cated by the program. Moreover, 20% of the total memory
allocated by the program was of medium sized objects
(between 33 and 256 bytes) by the function MAIN. The
<TOTAL> row represents the breakdown by size of all the
memory allocated by the program.
bytes kept The number of bytes allocated by this function that were
never freed (by calls to FREE).
% all kept The size breakdown of objects never freed by this func‐
tion as a percentage of all objects never freed. For
example, if <% all kept> values for function MAIN are
s=2, m=10, l=<blank>, x=<blank>, then 10% of the total
bytes not freed were allocated by MAIN and were allocated
in medium-sized chunks. The <TOTAL> row represents the
size breakdown of all the memory allocated but never
freed.
calls The number of times this function was called to allocate
an object.
name The name of the function.
TABLE 4: ALLOCATION CALL GRAPH
A star (*) indicates that this field is omitted for ancestors or
descendents in the same cycle as the function.
Cycles are listed twice. The first appearance shows all the functions
that are members of the cycle and the amount of memory allocated
locally in each function, including the breakdown of the local alloca‐
tion by size and the breakdown by size as a fraction of the total
cycle. The second appearance shows what the call graph would look like
if all the functions in the cycle were merged into a single function.
index A unique index used to aid searching for functions in the
call graph listing.
self + desc The percent of the total allocated memory that was allo‐
cated by this function and its descendents.
self (%) The number of bytes allocated by the function itself.
The percentage indicates the fraction of the bytes allo‐
cated by the function and its descendents that were allo‐
cated in the function itself.
size-func The size breakdown of objects allocated in the function
itself (not including its descendents.)
called The number of times this function was called while allo‐
cating memory.
recur The number of recursive function calls while allocating
memory.
name The function name including possible cycle membership and
index.
ANCESTOR LISTINGS
If the word ``all'' appears in the <self + desc> column, then this row
represents a summary of all the ancestors and presents the total number
of bytes requested by all ancestors in the <bytes> column, and the
breakdown of these bytes by size in the <self-ances> breakdown columns.
If there is only one ancestor, then this summary is omitted.
*self (%) The number of bytes allocated by the function and its
descendents that were allocated on behalf of this parent.
The percentage indicates what fraction of the total bytes
allocated by the function and its descendents were allo‐
cated on behalf of this parent.
*size-ances The size breakdown of the bytes allocated by the function
and its descendents on behalf of this parent.
*frac-ances The size breakdown of the objects allocated in the func‐
tion and its descendents on behalf of this parent as a
percentage of all objects allocated by the function and
its descendents. For example if parent P1 of function F
has <frac-ances> values s=<blank>, m=<blank>, l=30,
x=<blank>, then 30% of all objects allocated by F and its
descendents are of large objects allocated on behalf of
parent P1.
called The number of times this parent called this function
while requesting memory.
*total The number of calls this parent made requesting memory
from any function.
ancestors The name of the parent including possible cycle member‐
ship and index.
DESCENDENT LISTINGS
If the word ``all'' appears in the <self + desc> column, then this row
represents a summary of all the descendents and presents the total num‐
ber of bytes allocated by all descendents in the <bytes> column, and
the breakdown of these bytes by size in the <self-desc> breakdown col‐
umns. If there is only one descendent, then this summary is omitted.
*self (%) The number of bytes allocated in this descendent that
were allocated at the request of the function. The per‐
centage indicates what fraction of the total bytes allo‐
cated in descendents of the function were allocated in
this descendent.
*size-ances The size breakdown of the bytes allocated by this descen‐
dent on behalf of the function.
*frac-desc The size breakdown of the objects allocated in this
descendent on behalf of the function as a percentage of
all objects allocated by all descendents on behalf of
this function. For example if descendent C1 of function
F has <frac-desc> values s=35, m=<blank>, l=<blank>,
x=<blank>, then 35% of all objects allocated by children
of F on its behalf were allocated in child C1 and were
small objects.
called The number of times the function called this descendent
while requesting memory.
*total The number of times this descendent was called during a
memory request.
descendents The name of the child including possible cycle membership
and index.
FILES
a.out contains symbol table information.
mprof.data memory allocation call graph information.
libc_mp.a special version of malloc which profiles allocation.
(eventually to be put in /lib/local/mprof/libc_mp.a)
SEE ALSOcc(1), gprof(1)
A Memory Allocation Profiler for C and Lisp Programs, Benjamin Zorn and
Paul Hilfinger, Summer 1988 USENIX Conference.
AUTHOR
Written by Benjamin Zorn, zorn@ernie.berkeley.edu, as part of Ph.D.
research sponsored by the SPUR research project.
BUGS
The code that determines the names and sizes of user types is poorly
written and depends on the program being compiled with the -g option.
In some cases (mostly very simple cases) the user type names are not
correctly determined.
If the user application calls valloc or memalign and later tries to
free that memory, mprof will cause a segmentation fault.
mprof(1)