--- /dev/null
+.\" 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)
+.SH COLOPHON
+This page is part of release 3.75 of the Linux
+.I man-pages
+project.
+A description of the project,
+information about reporting bugs,
+and the latest version of this page,
+can be found at
+\%http://www.kernel.org/doc/man\-pages/.
OSDN Git Service
