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).
124 The "realloc/total memory" of the table output by
126 does not reflect cases where
128 is used to reallocate a block of memory
129 to have a smaller size than previously.
130 This can cause sum of all "total memory" cells (excluding "free")
131 to be larger than the "free/total memory" cell.
132 .SS Histogram for block sizes
133 The "Histogram for block sizes" provides a breakdown of memory
134 allocations into various bucket sizes.
137 .BI \-n\ name \fR,\ \fB\-\-progname= name
138 Name of the program file to profile.
140 .BI \-p\ file \fR,\ \fB\-\-png= file
141 Generate PNG graphic and store it in
144 .BI \-d\ file \fR,\ \fB\-\-data= file
145 Generate binary data file and store it in
148 .BI \-u\fR,\ \fB\-\-unbuffered
149 Do not buffer output.
151 .BI \-b\ size \fR,\ \fB\-\-buffer= size
154 entries before writing them out.
159 sampling of stack pointer value.
161 .BI \-m\fR,\ \fB\-\-mmap
168 .BI \-?\fR,\ \fB\-\-help
172 Print a short usage message and exit.
174 .BI \-V\fR,\ \fB\-\-version
175 Print version information and exit.
177 The following options apply only when generating graphical output:
179 .BI \-t\fR,\ \fB\-\-time\-based
180 Use time (rather than number of function calls) as the scale for the X axis.
182 .BI \-T\fR,\ \fB\-\-total
183 Also draw a graph of total memory use.
185 .BI \fB\-\-title= name
188 as the title of the graph.
190 .BI \-x\ size \fR,\ \fB\-\-x\-size= size
195 .BI \-y\ size \fR,\ \fB\-\-y\-size= size
200 Exit status is equal to the exit status of profiled program.
202 Below is a simple program that reallocates a block of
203 memory in cycles that rise to a peak before then cyclically
204 reallocating the memory in smaller blocks that return to zero.
205 After compiling the program and running the following commands,
206 a graph of the memory usage of the program can be found in the file
211 $ \fBmemusage --data=memusage.dat ./a.out\fP
213 Memory usage summary: heap total: 45200, heap peak: 6440, stack peak: 224
214 total calls total memory failed calls
216 realloc| 40 44800 0 (nomove:40, dec:19, free:0)
219 Histogram for block sizes:
220 192-207 1 2% ================
222 2192-2207 1 2% ================
223 2240-2255 2 4% =================================
224 2832-2847 2 4% =================================
225 3440-3455 2 4% =================================
226 4032-4047 2 4% =================================
227 4640-4655 2 4% =================================
228 5232-5247 2 4% =================================
229 5840-5855 2 4% =================================
230 6432-6447 1 2% ================
231 $ \fBmemusagestat memusage.dat memusage.png\fP
242 main(int argc, char *argv[])
247 printf("malloc: %zd\\n", sizeof(int) * 100);
248 p = malloc(sizeof(int) * 100);
250 for (i = 0; i < CYCLES; i++) {
256 printf("realloc: %zd\\n", sizeof(int) * (j * 50 + 110));
257 p = realloc(p, sizeof(int) * (j * 50 + 100));
259 printf("realloc: %zd\\n", sizeof(int) * ((j+1) * 150 + 110));
260 p = realloc(p, sizeof(int) * ((j + 1) * 150 + 110));
269 .UR http://www.gnu.org/software/libc/bugs.html
272 .BR memusagestat (1),