Debian Codegraph @

upstream/fedora-44/man1/memusage.1

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