Debian Codegraph @

upstream/debian-unstable/man1/memusage.1

raw
1 .\" Copyright 2013, Peter Schiffer <[email protected]>
2 .\" Copyright 2014, Michael Kerrisk <[email protected]>
3 .\" Copyright, the authors of the Linux man-pages project
4 .\"
5 .\" SPDX-License-Identifier: GPL-2.0-or-later
6 .\"
7 .TH memusage 1 2026-02-08 "Linux man-pages 6.18"
8 .SH NAME
9 memusage \- profile memory usage of a program
10 .SH SYNOPSIS
11 .SY memusage
12 .RI [ option \~.\|.\|.\&]
13 .I program
14 .RI [ programoption \~.\|.\|.]
15 .YS
16 .SH DESCRIPTION
17 .B memusage
18 is a
19 .BR bash (1)
20 script which profiles memory usage of the program,
21 .IR program .
22 It preloads the
23 .B libmemusage.so
24 library into the caller's environment (via the
25 .B LD_PRELOAD
26 environment variable;
27 see
28 .BR ld.so (8)).
29 The
30 .B libmemusage.so
31 library traces memory allocation by intercepting calls to
32 .BR malloc (3),
33 .BR calloc (3),
34 .BR free (3),
35 and
36 .BR realloc (3);
37 optionally, calls to
38 .BR mmap (2),
39 .BR mremap (2),
40 and
41 .BR munmap (2)
42 can also be intercepted.
43 .P
44 .B memusage
45 can output the collected data in textual form, or it can use
46 .BR memusagestat (1)
47 (see the
48 .B \-p
49 option, below)
50 to create a PNG file containing graphical representation
51 of the collected data.
52 .SS Memory usage summary
53 The "Memory usage summary" line output by
54 .B memusage
55 contains three fields:
56 .RS 4
57 .TP
58 .B heap total
59 Sum of
60 .I size
61 arguments of all
62 .BR malloc (3)
63 calls,
64 products of arguments
65 .RI ( n * size )
66 of all
67 .BR calloc (3)
68 calls,
69 and sum of
70 .I length
71 arguments of all
72 .BR mmap (2)
73 calls.
74 In the case of
75 .BR realloc (3)
76 and
77 .BR mremap (2),
78 if the new size of an allocation is larger than the previous size,
79 the sum of all such differences (new size minus old size) is added.
80 .TP
81 .B "heap peak"
82 Maximum of all
83 .I size
84 arguments of
85 .BR malloc (3),
86 all products of
87 .IR n * size
88 of
89 .BR calloc (3),
90 all
91 .I size
92 arguments of
93 .BR realloc (3),
94 .I length
95 arguments of
96 .BR mmap (2),
97 and
98 .I new_size
99 arguments of
100 .BR mremap (2).
101 .TP
102 .B "stack peak"
103 Before the first call to any monitored function,
104 the stack pointer address (base stack pointer) is saved.
105 After each function call, the actual stack pointer address is read and
106 the difference from the base stack pointer computed.
107 The maximum of these differences is then the stack peak.
108 .RE
109 .P
110 Immediately following this summary line, a table shows the number calls,
111 total memory allocated or deallocated,
112 and number of failed calls for each intercepted function.
113 For
114 .BR realloc (3)
115 and
116 .BR mremap (2),
117 the additional field "nomove" shows reallocations that
118 changed the address of a block,
119 and the additional "dec" field shows reallocations that
120 decreased the size of the block.
121 For
122 .BR realloc (3),
123 the additional field "free" shows reallocations that
124 caused a block to be freed (i.e., the reallocated size was 0).
125 .P
126 The "realloc/total memory" of the table output by
127 .B memusage
128 does not reflect cases where
129 .BR realloc (3)
130 is used to reallocate a block of memory
131 to have a smaller size than previously.
132 This can cause sum of all "total memory" cells (excluding "free")
133 to be larger than the "free/total memory" cell.
134 .SS Histogram for block sizes
135 The "Histogram for block sizes" provides a breakdown of memory
136 allocations into various bucket sizes.
137 .SH OPTIONS
138 .TP
139 .BI \-n\~ name
140 .TQ
141 .BI \-\-progname= name
142 Name of the program file to profile.
143 .TP
144 .BI \-p\~ file
145 .TQ
146 .BI \-\-png= file
147 Generate PNG graphic and store it in
148 .IR file .
149 .TP
150 .BI \-d\~ file
151 .TQ
152 .BI \-\-data= file
153 Generate binary data file and store it in
154 .IR file .
155 .TP
156 .B \-u
157 .TQ
158 .B \-\-unbuffered
159 Do not buffer output.
160 .TP
161 .BI \-b\~ size
162 .TQ
163 .BI \-\-buffer= size
164 Collect
165 .I size
166 entries before writing them out.
167 .TP
168 .B \-\-no\-timer
169 Disable timer-based
170 .RB ( SIGPROF )
171 sampling of stack pointer value.
172 .TP
173 .B \-m
174 .TQ
175 .B \-\-mmap
176 Also trace
177 .BR mmap (2),
178 .BR mremap (2),
179 and
180 .BR munmap (2).
181 .TP
182 .B \-?
183 .TQ
184 .B \-\-help
185 Print help and exit.
186 .TP
187 .B \-\-usage
188 Print a short usage message and exit.
189 .TP
190 .B \-V
191 .TQ
192 .B \-\-version
193 Print version information and exit.
194 .TP
195 The following options apply only when generating graphical output:
196 .TP
197 .B \-t
198 .TQ
199 .B \-\-time\-based
200 Use time (rather than number of function calls) as the scale for the X axis.
201 .TP
202 .B \-T
203 .TQ
204 .B \-\-total
205 Also draw a graph of total memory use.
206 .TP
207 .BI \-\-title= name
208 Use
209 .I name
210 as the title of the graph.
211 .TP
212 .BI \-x\~ size
213 .TQ
214 .BI \-\-x\-size= size
215 Make the graph
216 .I size
217 pixels wide.
218 .TP
219 .BI \-y\~ size
220 .TQ
221 .BI \-\-y\-size= size
222 Make the graph
223 .I size
224 pixels high.
225 .SH EXIT STATUS
226 The exit status of
227 .B memusage
228 is equal to the exit status of the profiled program.
229 .SH BUGS
230 To report bugs, see
231 .UR http:\://www.gnu.org/software/libc/bugs.html
232 .UE
233 .SH EXAMPLES
234 Below is a simple program that reallocates a block of
235 memory in cycles that rise to a peak before then cyclically
236 reallocating the memory in smaller blocks that return to zero.
237 After compiling the program and running the following commands,
238 a graph of the memory usage of the program can be found in the file
239 .IR memusage.png :
240 .P
241 .in +4n
242 .EX
243 .RB $ " memusage \-\-data=memusage.dat ./a.out" ;
244 \&...
245 Memory usage summary: heap total: 45200, heap peak: 6440, stack peak: 224
246 total calls total memory failed calls
247 malloc| 1 400 0
248 realloc| 40 44800 0 (nomove:40, dec:19, free:0)
249 calloc| 0 0 0
250 free| 1 440
251 Histogram for block sizes:
252 192\-207 1 2% ================
253 \&...
254 2192\-2207 1 2% ================
255 2240\-2255 2 4% =================================
256 2832\-2847 2 4% =================================
257 3440\-3455 2 4% =================================
258 4032\-4047 2 4% =================================
259 4640\-4655 2 4% =================================
260 5232\-5247 2 4% =================================
261 5840\-5855 2 4% =================================
262 6432\-6447 1 2% ================
263 .RB $ " memusagestat memusage.dat memusage.png" ;
264 .EE
265 .in
266 .SS Program source
267 .EX
268 #include <stdio.h>
269 #include <stdlib.h>
270 \&
271 #define CYCLES 20
272 \&
273 int
274 main(int argc, char *argv[])
275 {
276 int i, j;
277 size_t size;
278 int *p;
279 \&
280 size = sizeof(*p) * 100;
281 printf("malloc: %zu\[rs]n", size);
282 p = malloc(size);
283 \&
284 for (i = 0; i < CYCLES; i++) {
285 if (i < CYCLES / 2)
286 j = i;
287 else
288 j\-\-;
289 \&
290 size = sizeof(*p) * (j * 50 + 110);
291 printf("realloc: %zu\[rs]n", size);
292 p = realloc(p, size);
293 \&
294 size = sizeof(*p) * ((j + 1) * 150 + 110);
295 printf("realloc: %zu\[rs]n", size);
296 p = realloc(p, size);
297 }
298 \&
299 free(p);
300 exit(EXIT_SUCCESS);
301 }
302 .EE
303 .SH SEE ALSO
304 .BR memusagestat (1),
305 .BR mtrace (1),
306 .BR ld.so (8)