1memusage(1) General Commands Manual memusage(1)
2
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 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 Memory usage summary
24 The "Memory usage summary" line output by memusage contains three
25 fields:
26 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 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 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 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 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 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 -p file, --png=file
72 Generate PNG graphic and store it in file.
73 -d file, --data=file
75 Generate binary data file and store it in file.
76 -u, --unbuffered
78 Do not buffer output.
79 -b size, --buffer=size
81 Collect size entries before writing them out.
82 --no-timer
84 Disable timer-based (SIGPROF) sampling of stack pointer value.
85 -m, --mmap
87 Also trace mmap(2), mremap(2), and munmap(2).
88 -?, --help
90 Print help and exit.
91 --usage
93 Print a short usage message and exit.
94 -V, --version
96 Print version information and exit.
97 The following options apply only when generating graphical output:
99 -t, --time-based
101 Use time (rather than number of function calls) as the scale for
102 the X axis.
103 -T, --total
105 Also draw a graph of total memory use.
106 --title=name
108 Use name as the title of the graph.
109 -x size, --x-size=size
111 Make the graph size pixels wide.
112 -y size, --y-size=size
114 Make the graph size pixels high.
115
117 The exit status of memusage is equal to the exit status of the profiled
118 program.
119
121 To report bugs, see ⟨http://www.gnu.org/software/libc/bugs.html⟩
122
124 Below is a simple program that reallocates a block of memory in cycles
125 that rise to a peak before then cyclically reallocating the memory in
126 smaller blocks that return to zero. After compiling the program and
127 running the following commands, a graph of the memory usage of the pro‐
128 gram can be found in the file memusage.png:
129 $ memusage --data=memusage.dat ./a.out
131 ...
132 Memory usage summary: heap total: 45200, heap peak: 6440, stack peak: 224
133 total calls total memory failed calls
134 malloc| 1 400 0
135 realloc| 40 44800 0 (nomove:40, dec:19, free:0)
136 calloc| 0 0 0
137 free| 1 440
138 Histogram for block sizes:
139 192-207 1 2% ================
140 ...
141 2192-2207 1 2% ================
142 2240-2255 2 4% =================================
143 2832-2847 2 4% =================================
144 3440-3455 2 4% =================================
145 4032-4047 2 4% =================================
146 4640-4655 2 4% =================================
147 5232-5247 2 4% =================================
148 5840-5855 2 4% =================================
149 6432-6447 1 2% ================
150 $ memusagestat memusage.dat memusage.png
151 Program source
153 #include <stdio.h>
154 #include <stdlib.h>
155 #define CYCLES 20
157 int
159 main(int argc, char *argv[])
160 {
161 int i, j;
162 size_t size;
163 int *p;
164 size = sizeof(*p) * 100;
166 printf("malloc: %zu\n", size);
167 p = malloc(size);
168 for (i = 0; i < CYCLES; i++) {
170 if (i < CYCLES / 2)
171 j = i;
172 else
173 j--;
174 size = sizeof(*p) * (j * 50 + 110);
176 printf("realloc: %zu\n", size);
177 p = realloc(p, size);
178 size = sizeof(*p) * ((j + 1) * 150 + 110);
180 printf("realloc: %zu\n", size);
181 p = realloc(p, size);
182 }
183 free(p);
185 exit(EXIT_SUCCESS);
186 }
187
189 memusagestat(1), mtrace(1), ld.so(8)
190Linux man-pages 6.05 2023-05-03 memusage(1)