1MEMUSAGE(1)                    Linux user manual                   MEMUSAGE(1)
2
3
4

NAME

6       memusage - profile memory usage of a program
7

SYNOPSIS

9       memusage [option]... program [programoption]...
10

DESCRIPTION

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

OPTIONS

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

EXIT STATUS

117       Exit status is equal to the exit status of profiled program.
118

BUGS

120       To report bugs, see ⟨http://www.gnu.org/software/libc/bugs.html
121

EXAMPLE

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

SEE ALSO

184       memusagestat(1), mtrace(1) ld.so(8)
185

COLOPHON

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)
Impressum