memusage(1) General Commands Manual memusage(1)
NAME
memusage - profile memory usage of a program
SYNOPSIS
memusage [option]... program [programoption]...
DESCRIPTION
memusage is a bash script which profiles memory usage of the program,
program. It preloads the libmemusage.so library into the caller's envi-
ronment (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 con-
taining graphical representation of the collected data.
Memory usage summary
The "Memory usage summary" line output by memusage contains three
fields:
heap total
Sum of size arguments of all malloc(3) calls, products of ar-
guments (nmemb*size) of all calloc(3) calls, and sum of
length arguments of all mmap(2) calls. In the case of real-
loc(3) and mremap(2), if the new size of an allocation is
larger than the previous size, the sum of all such differ-
ences (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 re-
flect 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 mem-
ory" cell.
Histogram for block sizes
The "Histogram for block sizes" provides a breakdown of memory alloca-
tions into various bucket sizes.
OPTIONS
-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
The exit status of memusage is equal to the exit status of the profiled
program.
BUGS
To report bugs, see ]8;;http://www.gnu.org/software/libc/bugs.html\http://www.gnu.org/software/libc/bugs.html]8;;\
EXAMPLES
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 pro-
gram 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
Program source
#include <stdio.h>
#include <stdlib.h>
#define CYCLES 20
int
main(int argc, char *argv[])
{
int i, j;
size_t size;
int *p;
size = sizeof(*p) * 100;
printf("malloc: %zu\n", size);
p = malloc(size);
for (i = 0; i < CYCLES; i++) {
if (i < CYCLES / 2)
j = i;
else
j--;
size = sizeof(*p) * (j * 50 + 110);
printf("realloc: %zu\n", size);
p = realloc(p, size);
size = sizeof(*p) * ((j + 1) * 150 + 110);
printf("realloc: %zu\n", size);
p = realloc(p, size);
}
free(p);
exit(EXIT_SUCCESS);
}
SEE ALSO
memusagestat(1), mtrace(1), ld.so(8)
Linux man-pages 6.9.1 2024-06-15 memusage(1)
Generated by dwww version 1.16 on Tue Dec 16 04:28:24 CET 2025.