original/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 2014-09-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 .BR 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
 123
 124 The "realloc/total memory" of the table output by
 125 .B memusage
 126 does not reflect cases where
 127 .BR realloc (3)
 128 is used to reallocate a block of memory
 129 to have a smaller size than previously.
 130 This can cause sum of all "total memory" cells (excluding "free")
 131 to be larger than the "free/total memory" cell.
 132 .SS Histogram for block sizes
 133 The "Histogram for block sizes" provides a breakdown of memory
 134 allocations into various bucket sizes.
 135 .SH OPTIONS
 136 .TP
 137 .BI \-n\  name \fR,\ \fB\-\-progname= name
 138 Name of the program file to profile.
 139 .TP
 140 .BI \-p\  file \fR,\ \fB\-\-png= file
 141 Generate PNG graphic and store it in
 142 .IR file .
 143 .TP
 144 .BI \-d\  file \fR,\ \fB\-\-data= file
 145 Generate binary data file and store it in
 146 .IR file .
 147 .TP
 148 .BI \-u\fR,\ \fB\-\-unbuffered
 149 Do not buffer output.
 150 .TP
 151 .BI \-b\  size \fR,\ \fB\-\-buffer= size
 152 Collect
 153 .I size
 154 entries before writing them out.
 155 .TP
 156 .BI \fB\-\-no-timer
 157 Disable timer-based
 158 .RB ( SIGPROF )
 159 sampling of stack pointer value.
 160 .TP
 161 .BI \-m\fR,\ \fB\-\-mmap
 162 Also trace
 163 .BR mmap (2),
 164 .BR mremap (2),
 165 and
 166 .BR mmap (2).
 167 .TP
 168 .BI \-?\fR,\ \fB\-\-help
 169 Print help and exit.
 170 .TP
 171 .BI \fB\-\-usage
 172 Print a short usage message and exit.
 173 .TP
 174 .BI \-V\fR,\ \fB\-\-version
 175 Print version information and exit.
 176 .TP
 177 The following options apply only when generating graphical output:
 178 .TP
 179 .BI \-t\fR,\ \fB\-\-time\-based
 180 Use time (rather than number of function calls) as the scale for the X axis.
 181 .TP
 182 .BI \-T\fR,\ \fB\-\-total
 183 Also draw a graph of total memory use.
 184 .TP
 185 .BI \fB\-\-title= name
 186 Use
 187 .I name
 188 as the title of the graph.
 189 .TP
 190 .BI \-x\  size \fR,\ \fB\-\-x\-size= size
 191 Make the graph
 192 .I size
 193 pixels wide.
 194 .TP
 195 .BI \-y\  size \fR,\ \fB\-\-y\-size= size
 196 Make the graph
 197 .I size
 198 pixels high.
 199 .SH EXIT STATUS
 200 Exit status is equal to the exit status of profiled program.
 201 .SH EXAMPLE
 202 Below is a simple program that reallocates a block of
 203 memory in cycles that rise to a peak before then cyclically
 204 reallocating the memory in smaller blocks that return to zero.
 205 After compiling the program and running the following commands,
 206 a graph of the memory usage of the program can be found in the file
 207 .IR memusage.png :
 208
 209 .in +4n
 210 .nf
 211 $ \fBmemusage --data=memusage.dat ./a.out\fP
 212 \&...
 213 Memory usage summary: heap total: 45200, heap peak: 6440, stack peak: 224
 214         total calls  total memory  failed calls
 215  malloc|         1           400             0
 216 realloc|        40         44800             0  (nomove:40, dec:19, free:0)
 217  calloc|         0             0             0
 218    free|         1           440
 219 Histogram for block sizes:
 220   192-207             1   2% ================
 221 \&...
 222  2192-2207            1   2% ================
 223  2240-2255            2   4% =================================
 224  2832-2847            2   4% =================================
 225  3440-3455            2   4% =================================
 226  4032-4047            2   4% =================================
 227  4640-4655            2   4% =================================
 228  5232-5247            2   4% =================================
 229  5840-5855            2   4% =================================
 230  6432-6447            1   2% ================
 231 $ \fBmemusagestat memusage.dat memusage.png\fP
 232 .fi
 233 .in
 234 .SS Program source
 235 .nf
 236 #include <stdio.h>
 237 #include <stdlib.h>
 238
 239 #define CYCLES 20
 240
 241 int
 242 main(int argc, char *argv[])
 243 {
 244      int i, j;
 245      int *p;
 246
 247      printf("malloc: %zd\\n", sizeof(int) * 100);
 248      p = malloc(sizeof(int) * 100);
 249
 250      for (i = 0; i < CYCLES; i++) {
 251          if (i < CYCLES / 2)
 252              j = i;
 253          else
 254              j--;
 255
 256          printf("realloc: %zd\\n", sizeof(int) * (j * 50 + 110));
 257          p = realloc(p, sizeof(int) * (j * 50 + 100));
 258
 259          printf("realloc: %zd\\n", sizeof(int) * ((j+1) * 150 + 110));
 260          p = realloc(p, sizeof(int) * ((j + 1) * 150 + 110));
 261      }
 262
 263      free(p);
 264      exit(EXIT_SUCCESS);
 265 }
 266 .fi
 267 .SH BUGS
 268 To report bugs, see
 269 .UR http://www.gnu.org/software/libc/bugs.html
 270 .UE
 271 .SH SEE ALSO
 272 .BR memusagestat (1),
 273 .BR mtrace (1)
 274 .BR ld.so (8)
 275 .SH COLOPHON
 276 This page is part of release 3.79 of the Linux
 277 .I man-pages
 278 project.
 279 A description of the project,
 280 information about reporting bugs,
 281 and the latest version of this page,
 282 can be found at
 283 \%http://www.kernel.org/doc/man\-pages/.