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