mirror of https://github.com/mkerrisk/man-pages
275 lines
7.4 KiB
Groff
275 lines
7.4 KiB
Groff
.\" Copyright (c) 2013, Peter Schiffer <pschiffe@redhat.com>
|
|
.\" and Copyright (C) 2014, Michael Kerrisk <mtk.manpages@gmail.com>
|
|
.\"
|
|
.\" %%%LICENSE_START(GPLv2+_DOC_FULL)
|
|
.\" This is free documentation; you can redistribute it and/or
|
|
.\" modify it under the terms of the GNU General Public License as
|
|
.\" published by the Free Software Foundation; either version 2 of
|
|
.\" the License, or (at your option) any later version.
|
|
.\"
|
|
.\" The GNU General Public License's references to "object code"
|
|
.\" and "executables" are to be interpreted as the output of any
|
|
.\" document formatting or typesetting system, including
|
|
.\" intermediate and printed output.
|
|
.\"
|
|
.\" This manual is distributed in the hope that it will be useful,
|
|
.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
|
|
.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
|
|
.\" GNU General Public License for more details.
|
|
.\"
|
|
.\" You should have received a copy of the GNU General Public
|
|
.\" License along with this manual; if not, see
|
|
.\" <http://www.gnu.org/licenses/>.
|
|
.\" %%%LICENSE_END
|
|
.TH MEMUSAGE 1 2014-09-06 "GNU" "Linux user manual"
|
|
.SH NAME
|
|
memusage \- profile memory usage of a program
|
|
.SH SYNOPSIS
|
|
.BR memusage " [\fIoption\fR]... \fIprogram\fR [\fIprogramoption\fR]..."
|
|
.SH DESCRIPTION
|
|
.B memusage
|
|
is a bash script which profiles memory usage of the program,
|
|
.IR program .
|
|
It preloads the
|
|
.B libmemusage.so
|
|
library into the caller's environment (via the
|
|
.B LD_PRELOAD
|
|
environment variable; see
|
|
.BR ld.so (8)).
|
|
The
|
|
.B libmemusage.so
|
|
library traces memory allocation by intercepting calls to
|
|
.BR malloc (3),
|
|
.BR calloc (3),
|
|
.BR free (3),
|
|
and
|
|
.BR realloc (3);
|
|
optionally, calls to
|
|
.BR mmap (2),
|
|
.BR mremap (2),
|
|
and
|
|
.BR munmap (2)
|
|
can also be intercepted.
|
|
.PP
|
|
.B memusage
|
|
can output the collected data in textual form, or it can use
|
|
.BR memusagestat (1)
|
|
(see the
|
|
.B -p
|
|
option, below)
|
|
to create a PNG file containing graphical representation
|
|
of the collected data.
|
|
.SS Memory usage summary
|
|
The "Memory usage summary" line output by
|
|
.BR memusage
|
|
contains three fields:
|
|
.RS 4
|
|
.TP
|
|
\fBheap total\fR
|
|
Sum of \fIsize\fR arguments of all
|
|
.BR malloc (3)
|
|
calls,
|
|
products of arguments (\fInmemb\fR*\fIsize\fR) of all
|
|
.BR calloc (3)
|
|
calls,
|
|
and sum of \fIlength\fR arguments of all
|
|
.BR mmap (2)
|
|
calls.
|
|
In the case of
|
|
.BR realloc (3)
|
|
and
|
|
.BR 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.
|
|
.TP
|
|
.B "heap peak"
|
|
Maximum of all \fIsize\fR arguments of
|
|
.BR malloc (3),
|
|
all products of \fInmemb\fR*\fIsize\fR of
|
|
.BR calloc (3),
|
|
all \fIsize\fR arguments of
|
|
.BR realloc (3),
|
|
.I length
|
|
arguments of
|
|
.BR mmap (2),
|
|
and
|
|
\fInew_size\fR arguments of
|
|
.BR mremap (2).
|
|
.TP
|
|
.B "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.
|
|
.RE
|
|
.PP
|
|
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
|
|
.BR realloc (3)
|
|
and
|
|
.BR 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
|
|
.BR 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
|
|
.B memusage
|
|
does not reflect cases where
|
|
.BR 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.
|
|
.SS Histogram for block sizes
|
|
The "Histogram for block sizes" provides a breakdown of memory
|
|
allocations into various bucket sizes.
|
|
.SH OPTIONS
|
|
.TP
|
|
.BI \-n\ name \fR,\ \fB\-\-progname= name
|
|
Name of the program file to profile.
|
|
.TP
|
|
.BI \-p\ file \fR,\ \fB\-\-png= file
|
|
Generate PNG graphic and store it in
|
|
.IR file .
|
|
.TP
|
|
.BI \-d\ file \fR,\ \fB\-\-data= file
|
|
Generate binary data file and store it in
|
|
.IR file .
|
|
.TP
|
|
.BI \-u\fR,\ \fB\-\-unbuffered
|
|
Do not buffer output.
|
|
.TP
|
|
.BI \-b\ size \fR,\ \fB\-\-buffer= size
|
|
Collect
|
|
.I size
|
|
entries before writing them out.
|
|
.TP
|
|
.BI \fB\-\-no-timer
|
|
Disable timer-based
|
|
.RB ( SIGPROF )
|
|
sampling of stack pointer value.
|
|
.TP
|
|
.BI \-m\fR,\ \fB\-\-mmap
|
|
Also trace
|
|
.BR mmap (2),
|
|
.BR mremap (2),
|
|
and
|
|
.BR mmap (2).
|
|
.TP
|
|
.BI \-?\fR,\ \fB\-\-help
|
|
Print help and exit.
|
|
.TP
|
|
.BI \fB\-\-usage
|
|
Print a short usage message and exit.
|
|
.TP
|
|
.BI \-V\fR,\ \fB\-\-version
|
|
Print version information and exit.
|
|
.TP
|
|
The following options only apply when generating graphical output:
|
|
.TP
|
|
.BI \-t\fR,\ \fB\-\-time\-based
|
|
Use time (rather than number of function calls) as the scale for the X axis.
|
|
.TP
|
|
.BI \-T\fR,\ \fB\-\-total
|
|
Also draw a graph of total memory use.
|
|
.TP
|
|
.BI \fB\-\-title= name
|
|
Use
|
|
.I name
|
|
as the title of the graph.
|
|
.TP
|
|
.BI \-x\ size \fR,\ \fB\-\-x\-size= size
|
|
Make the graph
|
|
.I size
|
|
pixels wide.
|
|
.TP
|
|
.BI \-y\ size \fR,\ \fB\-\-y\-size= size
|
|
Make the graph
|
|
.I size
|
|
pixels high.
|
|
.SH EXIT STATUS
|
|
Exit status is equal to the exit status of profiled program.
|
|
.SH EXAMPLE
|
|
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
|
|
.IR memusage.png :
|
|
|
|
.in +4n
|
|
.nf
|
|
$ \fBmemusage --data=memusage.dat ./a.out\fP
|
|
\&...
|
|
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% ================
|
|
$ \fBmemusagestat memusage.dat memusage.png\fP
|
|
.fi
|
|
.in
|
|
.SS Program source
|
|
.nf
|
|
#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);
|
|
}
|
|
.fi
|
|
.SH BUGS
|
|
To report bugs, see
|
|
.UR http://www.gnu.org/software/libc/bugs.html
|
|
.UE
|
|
.SH SEE ALSO
|
|
.BR memusagestat (1),
|
|
.BR mtrace (1)
|
|
.BR ld.so (8)
|