+++ /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 apply only 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.79 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
