1MEMUSAGE(1) Linux user manual MEMUSAGE(1)
2
3
4
6 memusage - profile memory usage of a program
7
9 memusage [option]... program [programoption]...
10
12 memusage is a bash script which profiles memory usage of the program,
13 program. It preloads the libmemusage.so library into the caller's en‐
14 vironment (via the LD_PRELOAD environment variable; see ld.so(8)). The
15 libmemusage.so library traces memory allocation by intercepting calls
16 to malloc(3), calloc(3), free(3), and realloc(3); optionally, calls to
17 mmap(2), mremap(2), and munmap(2) can also be intercepted.
18
19 memusage can output the collected data in textual form, or it can use
20 memusagestat(1) (see the -p option, below) to create a PNG file con‐
21 taining graphical representation of the collected data.
22
23 Memory usage summary
24 The "Memory usage summary" line output by memusage contains three
25 fields:
26
27 heap total
28 Sum of size arguments of all malloc(3) calls, products of
29 arguments (nmemb*size) of all calloc(3) calls, and sum of
30 length arguments of all mmap(2) calls. In the case of real‐
31 loc(3) and mremap(2), if the new size of an allocation is
32 larger than the previous size, the sum of all such differ‐
33 ences (new size minus old size) is added.
34
35 heap peak
36 Maximum of all size arguments of malloc(3), all products of
37 nmemb*size of calloc(3), all size arguments of realloc(3),
38 length arguments of mmap(2), and new_size arguments of
39 mremap(2).
40
41 stack peak
42 Before the first call to any monitored function, the stack
43 pointer address (base stack pointer) is saved. After each
44 function call, the actual stack pointer address is read and
45 the difference from the base stack pointer computed. The
46 maximum of these differences is then the stack peak.
47
48 Immediately following this summary line, a table shows the number
49 calls, total memory allocated or deallocated, and number of failed
50 calls for each intercepted function. For realloc(3) and mremap(2), the
51 additional field "nomove" shows reallocations that changed the address
52 of a block, and the additional "dec" field shows reallocations that de‐
53 creased the size of the block. For realloc(3), the additional field
54 "free" shows reallocations that caused a block to be freed (i.e., the
55 reallocated size was 0).
56
57 The "realloc/total memory" of the table output by memusage does not re‐
58 flect cases where realloc(3) is used to reallocate a block of memory to
59 have a smaller size than previously. This can cause sum of all "total
60 memory" cells (excluding "free") to be larger than the "free/total mem‐
61 ory" cell.
62
63 Histogram for block sizes
64 The "Histogram for block sizes" provides a breakdown of memory alloca‐
65 tions into various bucket sizes.
66
68 -n name, --progname=name
69 Name of the program file to profile.
70
71 -p file, --png=file
72 Generate PNG graphic and store it in file.
73
74 -d file, --data=file
75 Generate binary data file and store it in file.
76
77 -u, --unbuffered
78 Do not buffer output.
79
80 -b size, --buffer=size
81 Collect size entries before writing them out.
82
83 --no-timer
84 Disable timer-based (SIGPROF) sampling of stack pointer value.
85
86 -m, --mmap
87 Also trace mmap(2), mremap(2), and munmap(2).
88
89 -?, --help
90 Print help and exit.
91
92 --usage
93 Print a short usage message and exit.
94
95 -V, --version
96 Print version information and exit.
97
98 The following options apply only when generating graphical output:
99
100 -t, --time-based
101 Use time (rather than number of function calls) as the scale for
102 the X axis.
103
104 -T, --total
105 Also draw a graph of total memory use.
106
107 --title=name
108 Use name as the title of the graph.
109
110 -x size, --x-size=size
111 Make the graph size pixels wide.
112
113 -y size, --y-size=size
114 Make the graph size pixels high.
115
117 Exit status is equal to the exit status of profiled program.
118
120 To report bugs, see ⟨http://www.gnu.org/software/libc/bugs.html⟩
121
123 Below is a simple program that reallocates a block of memory in cycles
124 that rise to a peak before then cyclically reallocating the memory in
125 smaller blocks that return to zero. After compiling the program and
126 running the following commands, a graph of the memory usage of the pro‐
127 gram can be found in the file memusage.png:
128
129 $ memusage --data=memusage.dat ./a.out
130 ...
131 Memory usage summary: heap total: 45200, heap peak: 6440, stack peak: 224
132 total calls total memory failed calls
133 malloc| 1 400 0
134 realloc| 40 44800 0 (nomove:40, dec:19, free:0)
135 calloc| 0 0 0
136 free| 1 440
137 Histogram for block sizes:
138 192-207 1 2% ================
139 ...
140 2192-2207 1 2% ================
141 2240-2255 2 4% =================================
142 2832-2847 2 4% =================================
143 3440-3455 2 4% =================================
144 4032-4047 2 4% =================================
145 4640-4655 2 4% =================================
146 5232-5247 2 4% =================================
147 5840-5855 2 4% =================================
148 6432-6447 1 2% ================
149 $ memusagestat memusage.dat memusage.png
150
151 Program source
152 #include <stdio.h>
153 #include <stdlib.h>
154
155 #define CYCLES 20
156
157 int
158 main(int argc, char *argv[])
159 {
160 int i, j;
161 size_t size;
162 int *p;
163
164 size = sizeof(*p) * 100;
165 printf("malloc: %zu\n", size);
166 p = malloc(size);
167
168 for (i = 0; i < CYCLES; i++) {
169 if (i < CYCLES / 2)
170 j = i;
171 else
172 j--;
173
174 size = sizeof(*p) * (j * 50 + 110);
175 printf("realloc: %zu\n", size);
176 p = realloc(p, size);
177
178 size = sizeof(*p) * ((j + 1) * 150 + 110);
179 printf("realloc: %zu\n", size);
180 p = realloc(p, size);
181 }
182
183 free(p);
184 exit(EXIT_SUCCESS);
185 }
186
188 memusagestat(1), mtrace(1), ld.so(8)
189
191 This page is part of release 5.10 of the Linux man-pages project. A
192 description of the project, information about reporting bugs, and the
193 latest version of this page, can be found at
194 https://www.kernel.org/doc/man-pages/.
195
196
197
198GNU 2020-11-01 MEMUSAGE(1)