memusage - profile memory usage of a program
memusage [
option]...
program [
programoption]...
memusage is a bash script which profiles memory usage of the program,
program. It preloads the
libmemusage.so library into the
caller's environment (via the
LD_PRELOAD environment variable; see
ld.so(8)). The
libmemusage.so library traces memory allocation
by intercepting calls to
malloc(3),
calloc(3),
free(3),
and
realloc(3); optionally, calls to
mmap(2),
mremap(2),
and
munmap(2) can also be intercepted.
memusage can output the collected data in textual form, or it can use
memusagestat(1) (see the
-p option, below) to create a PNG file
containing graphical representation of the collected data.
The "Memory usage summary" line output by
memusage contains
three fields:
- heap total
- Sum of size arguments of all malloc(3) calls, products of
arguments ( nmemb*size) of all calloc(3) calls, and
sum of length arguments of all mmap(2) calls. In the case of
realloc(3) and mremap(2), if the new size of an allocation
is larger than the previous size, the sum of all such differences (new
size minus old size) is added.
- heap peak
- Maximum of all size arguments of malloc(3), all products of
nmemb*size of calloc(3), all size arguments of
realloc(3), length arguments of mmap(2), and
new_size arguments of mremap(2).
- stack peak
- Before the first call to any monitored function, the stack pointer address
(base stack pointer) is saved. After each function call, the actual stack
pointer address is read and the difference from the base stack pointer
computed. The maximum of these differences is then the stack peak.
Immediately following this summary line, a table shows the number calls, total
memory allocated or deallocated, and number of failed calls for each
intercepted function. For
realloc(3) and
mremap(2), the
additional field "nomove" shows reallocations that changed the
address of a block, and the additional "dec" field shows
reallocations that decreased the size of the block. For
realloc(3), the
additional field "free" shows reallocations that caused a block to
be freed (i.e., the reallocated size was 0).
The "realloc/total memory" of the table output by
memusage does
not reflect cases where
realloc(3) is used to reallocate a block of
memory to have a smaller size than previously. This can cause sum of all
"total memory" cells (excluding "free") to be larger than
the "free/total memory" cell.
The "Histogram for block sizes" provides a breakdown of memory
allocations into various bucket sizes.
- -n name, --progname=name
- Name of the program file to profile.
- -p file, --png=file
- Generate PNG graphic and store it in file.
- -d file, --data=file
- Generate binary data file and store it in file.
- -u, --unbuffered
- Do not buffer output.
- -b size, --buffer=size
- Collect size entries before writing them out.
- --no-timer
- Disable timer-based (SIGPROF) sampling of stack pointer value.
- -m, --mmap
- Also trace mmap(2), mremap(2), and munmap(2).
- -?, --help
- Print help and exit.
- --usage
- Print a short usage message and exit.
- -V, --version
- Print version information and exit.
- The following options apply only when generating graphical output:
- -t, --time-based
- Use time (rather than number of function calls) as the scale for the X
axis.
- -T, --total
- Also draw a graph of total memory use.
- --title=name
- Use name as the title of the graph.
- -x size, --x-size=size
- Make the graph size pixels wide.
- -y size, --y-size=size
- Make the graph size pixels high.
Exit status is equal to the exit status of profiled program.
To report bugs, see
http://www.gnu.org/software/libc/bugs.html
Below is a simple program that reallocates a block of memory in cycles that rise
to a peak before then cyclically reallocating the memory in smaller blocks
that return to zero. After compiling the program and running the following
commands, a graph of the memory usage of the program can be found in the file
memusage.png:
$ memusage --data=memusage.dat ./a.out
...
Memory usage summary: heap total: 45200, heap peak: 6440, stack peak: 224
total calls total memory failed calls
malloc| 1 400 0
realloc| 40 44800 0 (nomove:40, dec:19, free:0)
calloc| 0 0 0
free| 1 440
Histogram for block sizes:
192-207 1 2% ================
...
2192-2207 1 2% ================
2240-2255 2 4% =================================
2832-2847 2 4% =================================
3440-3455 2 4% =================================
4032-4047 2 4% =================================
4640-4655 2 4% =================================
5232-5247 2 4% =================================
5840-5855 2 4% =================================
6432-6447 1 2% ================
$ memusagestat memusage.dat memusage.png
#include <stdio.h>
#include <stdlib.h>
#define CYCLES 20
int
main(int argc, char *argv[])
{
int i, j;
int *p;
printf("malloc: %zd\n", sizeof(int) * 100);
p = malloc(sizeof(int) * 100);
for (i = 0; i < CYCLES; i++) {
if (i < CYCLES / 2)
j = i;
else
j--;
printf("realloc: %zd\n", sizeof(int) * (j * 50 + 110));
p = realloc(p, sizeof(int) * (j * 50 + 100));
printf("realloc: %zd\n", sizeof(int) * ((j+1) * 150 + 110));
p = realloc(p, sizeof(int) * ((j + 1) * 150 + 110));
}
free(p);
exit(EXIT_SUCCESS);
}
memusagestat(1),
mtrace(1)
ld.so(8)