diff options
Diffstat (limited to 'man/man1/memusage.1')
| -rw-r--r-- | man/man1/memusage.1 | 262 |
1 files changed, 262 insertions, 0 deletions
diff --git a/man/man1/memusage.1 b/man/man1/memusage.1 new file mode 100644 index 000000000..b6793f6e8 --- /dev/null +++ b/man/man1/memusage.1 @@ -0,0 +1,262 @@ +.\" Copyright (c) 2013, Peter Schiffer <pschiffe@redhat.com> +.\" and Copyright (C) 2014, Michael Kerrisk <mtk.manpages@gmail.com> +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.TH memusage 1 (date) "Linux man-pages (unreleased)" +.SH NAME +memusage \- profile memory usage of a program +.SH SYNOPSIS +.nf +.BR memusage " [\fIoption\fR]... \fIprogram\fR [\fIprogramoption\fR]..." +.fi +.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. +.P +.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 +.B 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 +.P +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). +.P +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 +.B \-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 +.B \-\-no\-timer +Disable timer-based +.RB ( SIGPROF ) +sampling of stack pointer value. +.TP +.B \-m\fR,\ \fB\-\-mmap +Also trace +.BR mmap (2), +.BR mremap (2), +and +.BR munmap (2). +.TP +.B \-?\fR,\ \fB\-\-help +Print help and exit. +.TP +.B \-\-usage +Print a short usage message and exit. +.TP +.B \-V\fR,\ \fB\-\-version +Print version information and exit. +.TP +The following options apply only when generating graphical output: +.TP +.B \-t\fR,\ \fB\-\-time\-based +Use time (rather than number of function calls) as the scale for the X axis. +.TP +.B \-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 +The exit status of +.B memusage +is equal to the exit status of the profiled program. +.SH BUGS +To report bugs, see +.UR http://www.gnu.org/software/libc/bugs.html +.UE +.SH EXAMPLES +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 : +.P +.in +4n +.EX +$ \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 +.EE +.in +.SS Program source +.EX +#include <stdio.h> +#include <stdlib.h> +\& +#define CYCLES 20 +\& +int +main(int argc, char *argv[]) +{ + int i, j; + size_t size; + int *p; +\& + size = sizeof(*p) * 100; + printf("malloc: %zu\en", size); + p = malloc(size); +\& + for (i = 0; i < CYCLES; i++) { + if (i < CYCLES / 2) + j = i; + else + j\-\-; +\& + size = sizeof(*p) * (j * 50 + 110); + printf("realloc: %zu\en", size); + p = realloc(p, size); +\& + size = sizeof(*p) * ((j + 1) * 150 + 110); + printf("realloc: %zu\en", size); + p = realloc(p, size); + } +\& + free(p); + exit(EXIT_SUCCESS); +} +.EE +.SH SEE ALSO +.BR memusagestat (1), +.BR mtrace (1), +.BR ld.so (8) |