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 2014-09-06 "GNU" "Linux user manual"
26 memusage \- profile memory usage of a program
28 .BR memusage " [\fIoption\fR]... \fIprogram\fR [\fIprogramoption\fR]..."
31 is a bash script which profiles memory usage of the program,
35 library into the caller's environment (via the
37 environment variable; see
41 library traces memory allocation by intercepting calls to
52 can also be intercepted.
55 can output the collected data in textual form, or it can use
60 to create a PNG file containing graphical representation
61 of the collected data.
62 .SS Memory usage summary
63 The "Memory usage summary" line output by
65 contains three fields:
69 Sum of \fIsize\fR arguments of all
72 products of arguments (\fInmemb\fR*\fIsize\fR) of all
75 and sum of \fIlength\fR arguments of all
82 if the new size of an allocation is larger than the previous size,
83 the sum of all such differences (new size minus old size) is added.
86 Maximum of all \fIsize\fR arguments of
88 all products of \fInmemb\fR*\fIsize\fR of
90 all \fIsize\fR arguments of
96 \fInew_size\fR arguments of
100 Before the first call to any monitored function,
101 the stack pointer address (base stack pointer) is saved.
102 After each function call, the actual stack pointer address is read and
103 the difference from the base stack pointer computed.
104 The maximum of these differences is then the stack peak.
107 Immediately following this summary line, a table shows the number calls,
108 total memory allocated or deallocated,
109 and number of failed calls for each intercepted function.
114 the additional field "nomove" shows reallocations that
115 changed the address of a block,
116 and the additional "dec" field shows reallocations that
117 decreased the size of the block.
120 the additional field "free" shows reallocations that
121 caused a block to be freed (i.e., the reallocated size was 0).
123 The "realloc/total memory" of the table output by
125 does not reflect cases where
127 is used to reallocate a block of memory
128 to have a smaller size than previously.
129 This can cause sum of all "total memory" cells (excluding "free")
130 to be larger than the "free/total memory" cell.
131 .SS Histogram for block sizes
132 The "Histogram for block sizes" provides a breakdown of memory
133 allocations into various bucket sizes.
136 .BI \-n\ name \fR,\ \fB\-\-progname= name
137 Name of the program file to profile.
139 .BI \-p\ file \fR,\ \fB\-\-png= file
140 Generate PNG graphic and store it in
143 .BI \-d\ file \fR,\ \fB\-\-data= file
144 Generate binary data file and store it in
147 .BI \-u\fR,\ \fB\-\-unbuffered
148 Do not buffer output.
150 .BI \-b\ size \fR,\ \fB\-\-buffer= size
153 entries before writing them out.
158 sampling of stack pointer value.
160 .BI \-m\fR,\ \fB\-\-mmap
167 .BI \-?\fR,\ \fB\-\-help
171 Print a short usage message and exit.
173 .BI \-V\fR,\ \fB\-\-version
174 Print version information and exit.
176 The following options apply only when generating graphical output:
178 .BI \-t\fR,\ \fB\-\-time\-based
179 Use time (rather than number of function calls) as the scale for the X axis.
181 .BI \-T\fR,\ \fB\-\-total
182 Also draw a graph of total memory use.
184 .BI \fB\-\-title= name
187 as the title of the graph.
189 .BI \-x\ size \fR,\ \fB\-\-x\-size= size
194 .BI \-y\ size \fR,\ \fB\-\-y\-size= size
199 Exit status is equal to the exit status of profiled program.
202 .UR http://www.gnu.org/software/libc/bugs.html
205 Below is a simple program that reallocates a block of
206 memory in cycles that rise to a peak before then cyclically
207 reallocating the memory in smaller blocks that return to zero.
208 After compiling the program and running the following commands,
209 a graph of the memory usage of the program can be found in the file
214 $ \fBmemusage --data=memusage.dat ./a.out\fP
216 Memory usage summary: heap total: 45200, heap peak: 6440, stack peak: 224
217 total calls total memory failed calls
219 realloc| 40 44800 0 (nomove:40, dec:19, free:0)
222 Histogram for block sizes:
223 192-207 1 2% ================
225 2192-2207 1 2% ================
226 2240-2255 2 4% =================================
227 2832-2847 2 4% =================================
228 3440-3455 2 4% =================================
229 4032-4047 2 4% =================================
230 4640-4655 2 4% =================================
231 5232-5247 2 4% =================================
232 5840-5855 2 4% =================================
233 6432-6447 1 2% ================
234 $ \fBmemusagestat memusage.dat memusage.png\fP
245 main(int argc, char *argv[])
250 printf("malloc: %zd\\n", sizeof(int) * 100);
251 p = malloc(sizeof(int) * 100);
253 for (i = 0; i < CYCLES; i++) {
259 printf("realloc: %zd\\n", sizeof(int) * (j * 50 + 110));
260 p = realloc(p, sizeof(int) * (j * 50 + 100));
262 printf("realloc: %zd\\n", sizeof(int) * ((j+1) * 150 + 110));
263 p = realloc(p, sizeof(int) * ((j + 1) * 150 + 110));
271 .BR memusagestat (1),