]>
Commit | Line | Data |
---|---|---|
26ae4cd9 | 1 | .\" Copyright (c) 2013, Peter Schiffer <pschiffe@redhat.com> |
93aed984 | 2 | .\" and Copyright (C) 2014, Michael Kerrisk <mtk.manpages@gmail.com> |
5018c197 | 3 | .\" |
e4a74ca8 | 4 | .\" SPDX-License-Identifier: GPL-2.0-or-later |
45186a5d | 5 | .TH MEMUSAGE 1 2021-03-22 "Linux man-pages (unreleased)" |
5018c197 PS |
6 | .SH NAME |
7 | memusage \- profile memory usage of a program | |
8 | .SH SYNOPSIS | |
c7db92b9 | 9 | .nf |
5018c197 | 10 | .BR memusage " [\fIoption\fR]... \fIprogram\fR [\fIprogramoption\fR]..." |
c7db92b9 | 11 | .fi |
5018c197 PS |
12 | .SH DESCRIPTION |
13 | .B memusage | |
26ae4cd9 MK |
14 | is a bash script which profiles memory usage of the program, |
15 | .IR program . | |
16 | It preloads the | |
5018c197 | 17 | .B libmemusage.so |
26ae4cd9 | 18 | library into the caller's environment (via the |
5018c197 | 19 | .B LD_PRELOAD |
26ae4cd9 MK |
20 | environment variable; see |
21 | .BR ld.so (8)). | |
22 | The | |
5018c197 PS |
23 | .B libmemusage.so |
24 | library traces memory allocation by intercepting calls to | |
25 | .BR malloc (3), | |
26ae4cd9 | 26 | .BR calloc (3), |
5018c197 | 27 | .BR free (3), |
26ae4cd9 MK |
28 | and |
29 | .BR realloc (3); | |
30 | optionally, calls to | |
31 | .BR mmap (2), | |
32 | .BR mremap (2), | |
33 | and | |
34 | .BR munmap (2) | |
35 | can also be intercepted. | |
5018c197 PS |
36 | .PP |
37 | .B memusage | |
26ae4cd9 | 38 | can output the collected data in textual form, or it can use |
5018c197 | 39 | .BR memusagestat (1) |
26ae4cd9 | 40 | (see the |
8ef1d3d1 | 41 | .B \-p |
26ae4cd9 | 42 | option, below) |
5018c197 PS |
43 | to create a PNG file containing graphical representation |
44 | of the collected data. | |
26ae4cd9 MK |
45 | .SS Memory usage summary |
46 | The "Memory usage summary" line output by | |
a28b73cd | 47 | .B memusage |
26ae4cd9 MK |
48 | contains three fields: |
49 | .RS 4 | |
50 | .TP | |
51 | \fBheap total\fR | |
52 | Sum of \fIsize\fR arguments of all | |
53 | .BR malloc (3) | |
54 | calls, | |
55 | products of arguments (\fInmemb\fR*\fIsize\fR) of all | |
56 | .BR calloc (3) | |
57 | calls, | |
58 | and sum of \fIlength\fR arguments of all | |
59 | .BR mmap (2) | |
60 | calls. | |
41deb515 MK |
61 | In the case of |
62 | .BR realloc (3) | |
63 | and | |
64 | .BR mremap (2), | |
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. | |
26ae4cd9 MK |
67 | .TP |
68 | .B "heap peak" | |
69 | Maximum of all \fIsize\fR arguments of | |
70 | .BR malloc (3), | |
71 | all products of \fInmemb\fR*\fIsize\fR of | |
72 | .BR calloc (3), | |
73 | all \fIsize\fR arguments of | |
74 | .BR realloc (3), | |
75 | .I length | |
76 | arguments of | |
77 | .BR mmap (2), | |
78 | and | |
79 | \fInew_size\fR arguments of | |
80 | .BR mremap (2). | |
81 | .TP | |
82 | .B "stack peak" | |
5018c197 | 83 | Before the first call to any monitored function, |
26ae4cd9 MK |
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. | |
5018c197 | 88 | .RE |
26ae4cd9 | 89 | .PP |
41deb515 | 90 | Immediately following this summary line, a table shows the number calls, |
3fd38c0c | 91 | total memory allocated or deallocated, |
41deb515 | 92 | and number of failed calls for each intercepted function. |
983700ef MK |
93 | For |
94 | .BR realloc (3) | |
95 | and | |
96 | .BR mremap (2), | |
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. | |
101 | For | |
102 | .BR realloc (3), | |
103 | the additional field "free" shows reallocations that | |
104 | caused a block to be freed (i.e., the reallocated size was 0). | |
2a86152e | 105 | .PP |
41deb515 MK |
106 | The "realloc/total memory" of the table output by |
107 | .B memusage | |
108 | does not reflect cases where | |
26ae4cd9 MK |
109 | .BR realloc (3) |
110 | is used to reallocate a block of memory | |
41deb515 MK |
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. | |
26ae4cd9 MK |
114 | .SS Histogram for block sizes |
115 | The "Histogram for block sizes" provides a breakdown of memory | |
116 | allocations into various bucket sizes. | |
5018c197 PS |
117 | .SH OPTIONS |
118 | .TP | |
119 | .BI \-n\ name \fR,\ \fB\-\-progname= name | |
120 | Name of the program file to profile. | |
121 | .TP | |
122 | .BI \-p\ file \fR,\ \fB\-\-png= file | |
26ae4cd9 MK |
123 | Generate PNG graphic and store it in |
124 | .IR file . | |
5018c197 PS |
125 | .TP |
126 | .BI \-d\ file \fR,\ \fB\-\-data= file | |
26ae4cd9 MK |
127 | Generate binary data file and store it in |
128 | .IR file . | |
5018c197 | 129 | .TP |
a28b73cd | 130 | .B \-u\fR,\ \fB\-\-unbuffered |
5018c197 PS |
131 | Do not buffer output. |
132 | .TP | |
133 | .BI \-b\ size \fR,\ \fB\-\-buffer= size | |
26ae4cd9 MK |
134 | Collect |
135 | .I size | |
136 | entries before writing them out. | |
5018c197 | 137 | .TP |
28a4c58c | 138 | .B \-\-no\-timer |
26ae4cd9 MK |
139 | Disable timer-based |
140 | .RB ( SIGPROF ) | |
141 | sampling of stack pointer value. | |
5018c197 | 142 | .TP |
a28b73cd | 143 | .B \-m\fR,\ \fB\-\-mmap |
26ae4cd9 MK |
144 | Also trace |
145 | .BR mmap (2), | |
146 | .BR mremap (2), | |
147 | and | |
ff3e5500 | 148 | .BR munmap (2). |
5018c197 | 149 | .TP |
a28b73cd | 150 | .B \-?\fR,\ \fB\-\-help |
5018c197 PS |
151 | Print help and exit. |
152 | .TP | |
a28b73cd | 153 | .B \-\-usage |
5018c197 PS |
154 | Print a short usage message and exit. |
155 | .TP | |
a28b73cd | 156 | .B \-V\fR,\ \fB\-\-version |
5018c197 PS |
157 | Print version information and exit. |
158 | .TP | |
531fee2f | 159 | The following options apply only when generating graphical output: |
5018c197 | 160 | .TP |
a28b73cd | 161 | .B \-t\fR,\ \fB\-\-time\-based |
26ae4cd9 | 162 | Use time (rather than number of function calls) as the scale for the X axis. |
5018c197 | 163 | .TP |
a28b73cd | 164 | .B \-T\fR,\ \fB\-\-total |
26ae4cd9 | 165 | Also draw a graph of total memory use. |
5018c197 PS |
166 | .TP |
167 | .BI \fB\-\-title= name | |
26ae4cd9 MK |
168 | Use |
169 | .I name | |
170 | as the title of the graph. | |
5018c197 PS |
171 | .TP |
172 | .BI \-x\ size \fR,\ \fB\-\-x\-size= size | |
26ae4cd9 MK |
173 | Make the graph |
174 | .I size | |
175 | pixels wide. | |
5018c197 PS |
176 | .TP |
177 | .BI \-y\ size \fR,\ \fB\-\-y\-size= size | |
26ae4cd9 MK |
178 | Make the graph |
179 | .I size | |
180 | pixels high. | |
5018c197 | 181 | .SH EXIT STATUS |
30b0d8d9 | 182 | The exit status of |
1ae6b2c7 | 183 | .B memusage |
30b0d8d9 | 184 | is equal to the exit status of the profiled program. |
1b3e9b9c MK |
185 | .SH BUGS |
186 | To report bugs, see | |
187 | .UR http://www.gnu.org/software/libc/bugs.html | |
188 | .UE | |
a14af333 | 189 | .SH EXAMPLES |
3fd38c0c | 190 | Below is a simple program that reallocates a block of |
93aed984 MK |
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 | |
195 | .IR memusage.png : | |
2a86152e | 196 | .PP |
93aed984 | 197 | .in +4n |
60d3774e | 198 | .EX |
d2fdb1e3 | 199 | $ \fBmemusage \-\-data=memusage.dat ./a.out\fP |
93aed984 MK |
200 | \&... |
201 | Memory usage summary: heap total: 45200, heap peak: 6440, stack peak: 224 | |
202 | total calls total memory failed calls | |
203 | malloc| 1 400 0 | |
204 | realloc| 40 44800 0 (nomove:40, dec:19, free:0) | |
205 | calloc| 0 0 0 | |
206 | free| 1 440 | |
207 | Histogram for block sizes: | |
d2fdb1e3 | 208 | 192\-207 1 2% ================ |
93aed984 | 209 | \&... |
d2fdb1e3 MK |
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% ================ | |
93aed984 | 219 | $ \fBmemusagestat memusage.dat memusage.png\fP |
60d3774e | 220 | .EE |
93aed984 MK |
221 | .in |
222 | .SS Program source | |
e7d0bb47 | 223 | .EX |
93aed984 MK |
224 | #include <stdio.h> |
225 | #include <stdlib.h> | |
226 | ||
227 | #define CYCLES 20 | |
228 | ||
229 | int | |
230 | main(int argc, char *argv[]) | |
231 | { | |
d9f42b52 MK |
232 | int i, j; |
233 | size_t size; | |
234 | int *p; | |
93aed984 | 235 | |
d9f42b52 | 236 | size = sizeof(*p) * 100; |
d6c07484 | 237 | printf("malloc: %zu\en", size); |
d9f42b52 | 238 | p = malloc(size); |
93aed984 | 239 | |
d9f42b52 MK |
240 | for (i = 0; i < CYCLES; i++) { |
241 | if (i < CYCLES / 2) | |
242 | j = i; | |
243 | else | |
d064d41a | 244 | j\-\-; |
93aed984 | 245 | |
d9f42b52 | 246 | size = sizeof(*p) * (j * 50 + 110); |
d6c07484 | 247 | printf("realloc: %zu\en", size); |
d9f42b52 | 248 | p = realloc(p, size); |
93aed984 | 249 | |
d9f42b52 | 250 | size = sizeof(*p) * ((j + 1) * 150 + 110); |
d6c07484 | 251 | printf("realloc: %zu\en", size); |
d9f42b52 MK |
252 | p = realloc(p, size); |
253 | } | |
93aed984 | 254 | |
d9f42b52 MK |
255 | free(p); |
256 | exit(EXIT_SUCCESS); | |
93aed984 | 257 | } |
e7d0bb47 | 258 | .EE |
5018c197 PS |
259 | .SH SEE ALSO |
260 | .BR memusagestat (1), | |
bba4bbbd | 261 | .BR mtrace (1), |
5018c197 | 262 | .BR ld.so (8) |