1 .\" Copyright (c) 2013, Peter Schiffer <pschiffe@redhat.com>
2 .\" and Copyright (C) 2014, Michael Kerrisk <mtk.manpages@gmail.com>
4 .\" SPDX-License-Identifier: GPL-2.0-or-later
5 .TH MEMUSAGE 1 (date) "Linux man-pages (unreleased)"
7 memusage \- profile memory usage of a program
10 .BR memusage " [\fIoption\fR]... \fIprogram\fR [\fIprogramoption\fR]..."
14 is a bash script which profiles memory usage of the program,
18 library into the caller's environment (via the
20 environment variable; see
24 library traces memory allocation by intercepting calls to
35 can also be intercepted.
38 can output the collected data in textual form, or it can use
43 to create a PNG file containing graphical representation
44 of the collected data.
45 .SS Memory usage summary
46 The "Memory usage summary" line output by
48 contains three fields:
52 Sum of \fIsize\fR arguments of all
55 products of arguments (\fInmemb\fR*\fIsize\fR) of all
58 and sum of \fIlength\fR arguments of all
65 if the new size of an allocation is larger than the previous size,
66 the sum of all such differences (new size minus old size) is added.
69 Maximum of all \fIsize\fR arguments of
71 all products of \fInmemb\fR*\fIsize\fR of
73 all \fIsize\fR arguments of
79 \fInew_size\fR arguments of
83 Before the first call to any monitored function,
84 the stack pointer address (base stack pointer) is saved.
85 After each function call, the actual stack pointer address is read and
86 the difference from the base stack pointer computed.
87 The maximum of these differences is then the stack peak.
90 Immediately following this summary line, a table shows the number calls,
91 total memory allocated or deallocated,
92 and number of failed calls for each intercepted function.
97 the additional field "nomove" shows reallocations that
98 changed the address of a block,
99 and the additional "dec" field shows reallocations that
100 decreased the size of the block.
103 the additional field "free" shows reallocations that
104 caused a block to be freed (i.e., the reallocated size was 0).
106 The "realloc/total memory" of the table output by
108 does not reflect cases where
110 is used to reallocate a block of memory
111 to have a smaller size than previously.
112 This can cause sum of all "total memory" cells (excluding "free")
113 to be larger than the "free/total memory" cell.
114 .SS Histogram for block sizes
115 The "Histogram for block sizes" provides a breakdown of memory
116 allocations into various bucket sizes.
119 .BI \-n\ name \fR,\ \fB\-\-progname= name
120 Name of the program file to profile.
122 .BI \-p\ file \fR,\ \fB\-\-png= file
123 Generate PNG graphic and store it in
126 .BI \-d\ file \fR,\ \fB\-\-data= file
127 Generate binary data file and store it in
130 .B \-u\fR,\ \fB\-\-unbuffered
131 Do not buffer output.
133 .BI \-b\ size \fR,\ \fB\-\-buffer= size
136 entries before writing them out.
141 sampling of stack pointer value.
143 .B \-m\fR,\ \fB\-\-mmap
150 .B \-?\fR,\ \fB\-\-help
154 Print a short usage message and exit.
156 .B \-V\fR,\ \fB\-\-version
157 Print version information and exit.
159 The following options apply only when generating graphical output:
161 .B \-t\fR,\ \fB\-\-time\-based
162 Use time (rather than number of function calls) as the scale for the X axis.
164 .B \-T\fR,\ \fB\-\-total
165 Also draw a graph of total memory use.
167 .BI \fB\-\-title= name
170 as the title of the graph.
172 .BI \-x\ size \fR,\ \fB\-\-x\-size= size
177 .BI \-y\ size \fR,\ \fB\-\-y\-size= size
184 is equal to the exit status of the profiled program.
187 .UR http://www.gnu.org/software/libc/bugs.html
190 Below is a simple program that reallocates a block of
191 memory in cycles that rise to a peak before then cyclically
192 reallocating the memory in smaller blocks that return to zero.
193 After compiling the program and running the following commands,
194 a graph of the memory usage of the program can be found in the file
199 $ \fBmemusage \-\-data=memusage.dat ./a.out\fP
201 Memory usage summary: heap total: 45200, heap peak: 6440, stack peak: 224
202 total calls total memory failed calls
204 realloc| 40 44800 0 (nomove:40, dec:19, free:0)
207 Histogram for block sizes:
208 192\-207 1 2% ================
210 2192\-2207 1 2% ================
211 2240\-2255 2 4% =================================
212 2832\-2847 2 4% =================================
213 3440\-3455 2 4% =================================
214 4032\-4047 2 4% =================================
215 4640\-4655 2 4% =================================
216 5232\-5247 2 4% =================================
217 5840\-5855 2 4% =================================
218 6432\-6447 1 2% ================
219 $ \fBmemusagestat memusage.dat memusage.png\fP
230 main(int argc, char *argv[])
236 size = sizeof(*p) * 100;
237 printf("malloc: %zu\en", size);
240 for (i = 0; i < CYCLES; i++) {
246 size = sizeof(*p) * (j * 50 + 110);
247 printf("realloc: %zu\en", size);
248 p = realloc(p, size);
250 size = sizeof(*p) * ((j + 1) * 150 + 110);
251 printf("realloc: %zu\en", size);
252 p = realloc(p, size);
260 .BR memusagestat (1),