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