mirror of https://github.com/mkerrisk/man-pages
159 lines
4.8 KiB
Groff
159 lines
4.8 KiB
Groff
|
.\" Copyright (c) 2013, Peter Schiffer (pschiffe@redhat.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 2013-04-10 "GNU glibc 2.18" "Memory diagnostic tools"
|
||
|
.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 can profile memory usage of a program. It preloads
|
||
|
.B libmemusage.so
|
||
|
library to the user's environment using
|
||
|
.B LD_PRELOAD
|
||
|
environment variable. The
|
||
|
.B libmemusage.so
|
||
|
library traces memory allocation by intercepting calls to
|
||
|
.BR malloc (3),
|
||
|
.BR free (3),
|
||
|
.BR realloc (3)
|
||
|
and various other calls.
|
||
|
.PP
|
||
|
.B memusage
|
||
|
can output text representation of the collected data, or it can use
|
||
|
.BR memusagestat (1)
|
||
|
utility (see
|
||
|
.B -p
|
||
|
option)
|
||
|
to create a PNG file containing graphical representation
|
||
|
of the collected data.
|
||
|
.TP
|
||
|
List of monitored functions:
|
||
|
.RS
|
||
|
.BI "void *malloc(size_t " "size" );
|
||
|
.RE
|
||
|
.RS
|
||
|
.BI "void *calloc(size_t " "nmemb" ", size_t " "size" );
|
||
|
.RE
|
||
|
.RS
|
||
|
.BI "void *realloc(void " "*ptr" ", size_t " "size" );
|
||
|
.RE
|
||
|
.RS
|
||
|
.BI "void *mmap(void " "*addr" ", size_t " "length" ", int " "prot",
|
||
|
.BI "int " "flags" ", int " "fd" ", off_t " "offset");
|
||
|
.RE
|
||
|
.RS
|
||
|
.BI "void *mremap(void " "*old_address" ", size_t " "old_size",
|
||
|
.BI "size_t " "new_size" ", int " "flags",
|
||
|
.BI "... /* void " "*new_address" " */);"
|
||
|
.RE
|
||
|
.TP
|
||
|
Description of a memory usage summary:
|
||
|
.RE
|
||
|
\fBheap total\fR:
|
||
|
.RS
|
||
|
Sum of \fIsize\fR arguments of all malloc calls,
|
||
|
sum of all product of arguments (\fInmemb\fR*\fIsize\fR) of calloc call
|
||
|
and sum of \fIlength\fR arguments of mmap calls.
|
||
|
In a case of realloc, respectively mremap, if a new size of an original
|
||
|
malloc,
|
||
|
respectively mremap call is bigger than an old one,
|
||
|
sum of all such differences (new size - old size) is added.
|
||
|
.RE
|
||
|
\fBheap peak\fR:
|
||
|
.RS
|
||
|
Maximum of all \fIsize\fR arguments of malloc,
|
||
|
all products of \fInmemb\fR*\fIsize\fR of calloc,
|
||
|
all \fIsize\fR arguments of realloc, \fIlength\fR arguments of mmap and
|
||
|
\fInew_size\fR arguments of mremap.
|
||
|
.RE
|
||
|
\fBstack peak\fR:
|
||
|
.RS
|
||
|
Before the first call to any monitored function,
|
||
|
stack pointer address (base stack pointer) is saved.
|
||
|
After each function call, actual stack pointer address is read and
|
||
|
the difference between the base stack pointer computed.
|
||
|
Maximum of these differences is then the stack peak.
|
||
|
.RE
|
||
|
|
||
|
If a realloc function is called on a mallocced memory with a new size being
|
||
|
smaller than an old one, total memory of realloc cell is not updated.
|
||
|
This can cause sum of all cells (excluding free) of total memory being
|
||
|
greater than free cell.
|
||
|
.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 the file.
|
||
|
.TP
|
||
|
.BI \-d\ file \fR,\ \fB\-\-data= file
|
||
|
Generate binary data file and store it in the file.
|
||
|
.TP
|
||
|
.BI \-u\fR,\ \fB\-\-unbuffered
|
||
|
Do not buffer output.
|
||
|
.TP
|
||
|
.BI \-b\ size \fR,\ \fB\-\-buffer= size
|
||
|
Collect size entries before writing them out.
|
||
|
.TP
|
||
|
.BI \fB\-\-no-timer
|
||
|
Do not collect additional information through timer.
|
||
|
.TP
|
||
|
.BI \-m\fR,\ \fB\-\-mmap
|
||
|
Also trace mmap and friends.
|
||
|
.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
|
||
|
Make graph linear in time.
|
||
|
.TP
|
||
|
.BI \-T\fR,\ \fB\-\-total
|
||
|
Also draw graph of total memory use.
|
||
|
.TP
|
||
|
.BI \fB\-\-title= name
|
||
|
Use the name as a title of the graph.
|
||
|
.TP
|
||
|
.BI \-x\ size \fR,\ \fB\-\-x\-size= size
|
||
|
Make graphic size pixels wide.
|
||
|
.TP
|
||
|
.BI \-y\ size \fR,\ \fB\-\-y\-size= size
|
||
|
Make graphic size pixels high.
|
||
|
.SH EXIT STATUS
|
||
|
Exit status is equal to the exit status of profiled program.
|
||
|
.SH BUGS
|
||
|
For bug reporting instructions, please see:
|
||
|
<http://www.gnu.org/software/libc/bugs.html>.
|
||
|
.SH SEE ALSO
|
||
|
.BR memusagestat (1),
|
||
|
.BR ld.so (8)
|