Thank you
Jan
.\" 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)