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
14 environment (via the LD_PRELOAD environment variable; see ld.so(8)).
15 The libmemusage.so library traces memory allocation by intercepting
16 calls to malloc(3), calloc(3), free(3), and realloc(3); optionally,
17 calls to 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
53 decreased 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
58 reflect cases where realloc(3) is used to reallocate a block of memory
59 to have a smaller size than previously. This can cause sum of all
60 "total memory" cells (excluding "free") to be larger than the
61 "free/total memory" 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 int *p;
162
163 printf("malloc: %zd\n", sizeof(int) * 100);
164 p = malloc(sizeof(int) * 100);
165
166 for (i = 0; i < CYCLES; i++) {
167 if (i < CYCLES / 2)
168 j = i;
169 else
170 j--;
171
172 printf("realloc: %zd\n", sizeof(int) * (j * 50 + 110));
173 p = realloc(p, sizeof(int) * (j * 50 + 100));
174
175 printf("realloc: %zd\n", sizeof(int) * ((j+1) * 150 + 110));
176 p = realloc(p, sizeof(int) * ((j + 1) * 150 + 110));
177 }
178
179 free(p);
180 exit(EXIT_SUCCESS);
181 }
182
184 memusagestat(1), mtrace(1) ld.so(8)
185
187 This page is part of release 5.04 of the Linux man-pages project. A
188 description of the project, information about reporting bugs, and the
189 latest version of this page, can be found at
190 https://www.kernel.org/doc/man-pages/.
191
192
193
194GNU 2019-03-06 MEMUSAGE(1)