1 .\" Copyright (c) 2013, Peter Schiffer <pschiffe@redhat.com>
2 .\" and Copyright (C) 2014, Michael Kerrisk <mtk.manpages@gmail.com>
4 .\" %%%LICENSE_START(GPLv2+_DOC_FULL)
5 .\" This is free documentation; you can redistribute it and/or
6 .\" modify it under the terms of the GNU General Public License as
7 .\" published by the Free Software Foundation; either version 2 of
8 .\" the License, or (at your option) any later version.
10 .\" The GNU General Public License's references to "object code"
11 .\" and "executables" are to be interpreted as the output of any
12 .\" document formatting or typesetting system, including
13 .\" intermediate and printed output.
15 .\" This manual is distributed in the hope that it will be useful,
16 .\" but WITHOUT ANY WARRANTY; without even the implied warranty of
17 .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
18 .\" GNU General Public License for more details.
20 .\" You should have received a copy of the GNU General Public
21 .\" License along with this manual; if not, see
22 .\" <http://www.gnu.org/licenses/>.
24 .TH MEMUSAGE 1 2021-03-22 "GNU" "Linux user manual"
26 memusage \- profile memory usage of a program
29 .BR memusage " [\fIoption\fR]... \fIprogram\fR [\fIprogramoption\fR]..."
33 is a bash script which profiles memory usage of the program,
37 library into the caller's environment (via the
39 environment variable; see
43 library traces memory allocation by intercepting calls to
54 can also be intercepted.
57 can output the collected data in textual form, or it can use
62 to create a PNG file containing graphical representation
63 of the collected data.
64 .SS Memory usage summary
65 The "Memory usage summary" line output by
67 contains three fields:
71 Sum of \fIsize\fR arguments of all
74 products of arguments (\fInmemb\fR*\fIsize\fR) of all
77 and sum of \fIlength\fR arguments of all
84 if the new size of an allocation is larger than the previous size,
85 the sum of all such differences (new size minus old size) is added.
88 Maximum of all \fIsize\fR arguments of
90 all products of \fInmemb\fR*\fIsize\fR of
92 all \fIsize\fR arguments of
98 \fInew_size\fR arguments of
102 Before the first call to any monitored function,
103 the stack pointer address (base stack pointer) is saved.
104 After each function call, the actual stack pointer address is read and
105 the difference from the base stack pointer computed.
106 The maximum of these differences is then the stack peak.
109 Immediately following this summary line, a table shows the number calls,
110 total memory allocated or deallocated,
111 and number of failed calls for each intercepted function.
116 the additional field "nomove" shows reallocations that
117 changed the address of a block,
118 and the additional "dec" field shows reallocations that
119 decreased the size of the block.
122 the additional field "free" shows reallocations that
123 caused a block to be freed (i.e., the reallocated size was 0).
125 The "realloc/total memory" of the table output by
127 does not reflect cases where
129 is used to reallocate a block of memory
130 to have a smaller size than previously.
131 This can cause sum of all "total memory" cells (excluding "free")
132 to be larger than the "free/total memory" cell.
133 .SS Histogram for block sizes
134 The "Histogram for block sizes" provides a breakdown of memory
135 allocations into various bucket sizes.
138 .BI \-n\ name \fR,\ \fB\-\-progname= name
139 Name of the program file to profile.
141 .BI \-p\ file \fR,\ \fB\-\-png= file
142 Generate PNG graphic and store it in
145 .BI \-d\ file \fR,\ \fB\-\-data= file
146 Generate binary data file and store it in
149 .B \-u\fR,\ \fB\-\-unbuffered
150 Do not buffer output.
152 .BI \-b\ size \fR,\ \fB\-\-buffer= size
155 entries before writing them out.
160 sampling of stack pointer value.
162 .B \-m\fR,\ \fB\-\-mmap
169 .B \-?\fR,\ \fB\-\-help
173 Print a short usage message and exit.
175 .B \-V\fR,\ \fB\-\-version
176 Print version information and exit.
178 The following options apply only when generating graphical output:
180 .B \-t\fR,\ \fB\-\-time\-based
181 Use time (rather than number of function calls) as the scale for the X axis.
183 .B \-T\fR,\ \fB\-\-total
184 Also draw a graph of total memory use.
186 .BI \fB\-\-title= name
189 as the title of the graph.
191 .BI \-x\ size \fR,\ \fB\-\-x\-size= size
196 .BI \-y\ size \fR,\ \fB\-\-y\-size= size
203 is equal to the exit status of the profiled program.
206 .UR http://www.gnu.org/software/libc/bugs.html
209 Below is a simple program that reallocates a block of
210 memory in cycles that rise to a peak before then cyclically
211 reallocating the memory in smaller blocks that return to zero.
212 After compiling the program and running the following commands,
213 a graph of the memory usage of the program can be found in the file
218 $ \fBmemusage \-\-data=memusage.dat ./a.out\fP
220 Memory usage summary: heap total: 45200, heap peak: 6440, stack peak: 224
221 total calls total memory failed calls
223 realloc| 40 44800 0 (nomove:40, dec:19, free:0)
226 Histogram for block sizes:
227 192\-207 1 2% ================
229 2192\-2207 1 2% ================
230 2240\-2255 2 4% =================================
231 2832\-2847 2 4% =================================
232 3440\-3455 2 4% =================================
233 4032\-4047 2 4% =================================
234 4640\-4655 2 4% =================================
235 5232\-5247 2 4% =================================
236 5840\-5855 2 4% =================================
237 6432\-6447 1 2% ================
238 $ \fBmemusagestat memusage.dat memusage.png\fP
249 main(int argc, char *argv[])
255 size = sizeof(*p) * 100;
256 printf("malloc: %zu\en", size);
259 for (i = 0; i < CYCLES; i++) {
265 size = sizeof(*p) * (j * 50 + 110);
266 printf("realloc: %zu\en", size);
267 p = realloc(p, size);
269 size = sizeof(*p) * ((j + 1) * 150 + 110);
270 printf("realloc: %zu\en", size);
271 p = realloc(p, size);
279 .BR memusagestat (1),