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