| .\" 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 2021-03-22 "GNU" "Linux user manual" |
| .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. |
| .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 |
| .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 |
| .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). |
| .PP |
| 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 |
| .BR 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 : |
| .PP |
| .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) |