man1/memusage.1

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