This is the mail archive of the mailing list for the glibc project.

Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]
Other format: [Raw text]

Re: memusage (1) man page

On 09/01/2014 05:39 PM, Michael Kerrisk (man-pages) wrote:
Hello Jan,

On 09/01/2014 09:18 AM, Jan Chaloupka wrote:

memusage man page.
Thank you for submitting this page on Peter's behalf. I've merged it.

I edited both pages quite substantially, doing some clean up
for man-pages style, and also adding many details to the memusage.1
page. And--because I added various extra explanatory text about the
output of memusage(1) and showed some of the sample output that
results from memusage(1)--it seemed more sensible to have the EXAMPLE
in the memusage.1 page, so I moved it from memusagestat.1 to here.

You can find both updated pages in Git. I've also appended the
revised memusage.1 page here, in case you or Peter would like to
check it over.

Thank you very much, Michael.



.\" Copyright (c) 2013, Peter Schiffer <>
.\" and Copyright (C) 2014, Michael Kerrisk <>
.\" This is free documentation; you can redistribute it and/or
.\" modify it under the terms of the GNU General Public License as
.\" published by the Free Software Foundation; either version 2 of
.\" the License, or (at your option) any later version.
.\" The GNU General Public License's references to "object code"
.\" and "executables" are to be interpreted as the output of any
.\" document formatting or typesetting system, including
.\" intermediate and printed output.
.\" This manual is distributed in the hope that it will be useful,
.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
.\" GNU General Public License for more details.
.\" You should have received a copy of the GNU General Public
.\" License along with this manual; if not, see
.\" <>.
.TH MEMUSAGE 1 2013-04-10 "GNU" "Linux user manual"
memusage \- profile memory usage of a program
.BR memusage " [\fIoption\fR]... \fIprogram\fR [\fIprogramoption\fR]..."
.B memusage
is a bash script which profiles memory usage of the program,
.IR program .
It preloads the
library into the caller's environment (via the
environment variable; see
.BR (8)).
library traces memory allocation by intercepting calls to
.BR malloc (3),
.BR calloc (3),
.BR free (3),
.BR realloc (3);
optionally, calls to
.BR mmap (2),
.BR mremap (2),
.BR munmap (2)
can also be intercepted.
.B memusage
can output the collected data in textual form, or it can use
.BR memusagestat (1)
(see the
.B -p
option,  below)
to create a PNG file containing graphical representation
of the collected data.
.SS Memory usage summary
The "Memory usage summary" line output by
.BR memusage
contains three fields:
.RS 4
\fBheap total\fR
Sum of \fIsize\fR arguments of all
.BR malloc (3)
products of arguments (\fInmemb\fR*\fIsize\fR) of all
.BR calloc (3)
and sum of \fIlength\fR arguments of all
.BR mmap (2)
In the case of
.BR realloc (3)
.BR mremap (2),
if the new size of an allocation is larger than the previous size,
the sum of all such differences (new size minus old size) is added.
.B "heap peak"
Maximum of all \fIsize\fR arguments of
.BR malloc (3),
all products of \fInmemb\fR*\fIsize\fR of
.BR calloc (3),
all \fIsize\fR arguments of
.BR realloc (3),
.I length
arguments of
.BR mmap (2),
\fInew_size\fR arguments of
.BR mremap (2).
.B "stack peak"
Before the first call to any monitored function,
the stack pointer address (base stack pointer) is saved.
After each function call, the actual stack pointer address is read and
the difference from the base stack pointer computed.
The maximum of these differences is then the stack peak.
Immediately following this summary line, a table shows the number calls,
total memory allocated or deallocated,
and number of failed calls for each intercepted function.
.BR realloc (3)
.BR mremap (2),
the additional field "nomove" shows reallocations that
changed the address of a block,
and the additional "dec" field shows reallocations that
decreased the size of the block.
.BR realloc (3),
the additional field "free" shows reallocations that
caused a block to be freed (i.e., the reallocated size was 0).

The "realloc/total memory" of the table output by
.B memusage
does not reflect cases where
.BR realloc (3)
is used to reallocate a block of memory
to have a smaller size than previously.
This can cause sum of all "total memory" cells (excluding "free")
to be larger than the "free/total memory" cell.
.SS Histogram for block sizes
The "Histogram for block sizes" provides a breakdown of memory
allocations into various bucket sizes.
.BI \-n\  name \fR,\ \fB\-\-progname= name
Name of the program file to profile.
.BI \-p\  file \fR,\ \fB\-\-png= file
Generate PNG graphic and store it in
.IR file .
.BI \-d\  file \fR,\ \fB\-\-data= file
Generate binary data file and store it in
.IR file .
.BI \-u\fR,\ \fB\-\-unbuffered
Do not buffer output.
.BI \-b\  size \fR,\ \fB\-\-buffer= size
.I size
entries before writing them out.
.BI \fB\-\-no-timer
Disable timer-based
sampling of stack pointer value.
.BI \-m\fR,\ \fB\-\-mmap
Also trace
.BR mmap (2),
.BR mremap (2),
.BR mmap (2).
.BI \-?\fR,\ \fB\-\-help
Print help and exit.
.BI \fB\-\-usage
Print a short usage message and exit.
.BI \-V\fR,\ \fB\-\-version
Print version information and exit.
The following options only apply when generating graphical output:
.BI \-t\fR,\ \fB\-\-time\-based
Use time (rather than number of function calls) as the scale for the X axis.
.BI \-T\fR,\ \fB\-\-total
Also draw a graph of total memory use.
.BI \fB\-\-title= name
.I name
as the title of the graph.
.BI \-x\  size \fR,\ \fB\-\-x\-size= size
Make the graph
.I size
pixels wide.
.BI \-y\  size \fR,\ \fB\-\-y\-size= size
Make the graph
.I size
pixels high.
Exit status is equal to the exit status of profiled program.
Below is a simple program that reallocates a block of
memory in cycles that rise to a peak before then cyclically
reallocating the memory in smaller blocks that return to zero.
After compiling the program and running the following commands,
a graph of the memory usage of the program can be found in the file
.IR memusage.png :

.in +4n
$ \fBmemusage --data=memusage.dat ./a.out\fP
Memory usage summary: heap total: 45200, heap peak: 6440, stack peak: 224
         total calls  total memory  failed calls
  malloc|         1           400             0
realloc|        40         44800             0  (nomove:40, dec:19, free:0)
  calloc|         0             0             0
    free|         1           440
Histogram for block sizes:
   192-207             1   2% ================
  2192-2207            1   2% ================
  2240-2255            2   4% =================================
  2832-2847            2   4% =================================
  3440-3455            2   4% =================================
  4032-4047            2   4% =================================
  4640-4655            2   4% =================================
  5232-5247            2   4% =================================
  5840-5855            2   4% =================================
  6432-6447            1   2% ================
$ \fBmemusagestat memusage.dat memusage.png\fP
.SS Program source
#include <stdio.h>
#include <stdlib.h>

#define CYCLES 20

main(int argc, char *argv[])
      int i, j;
      int *p;

      printf("malloc: %zd\\n", sizeof(int) * 100);
      p = malloc(sizeof(int) * 100);

      for (i = 0; i < CYCLES; i++) {
          if (i < CYCLES / 2)
              j = i;

          printf("realloc: %zd\\n", sizeof(int) * (j * 50 + 110));
          p = realloc(p, sizeof(int) * (j * 50 + 100));

          printf("realloc: %zd\\n", sizeof(int) * ((j+1) * 150 + 110));
          p = realloc(p, sizeof(int) * ((j + 1) * 150 + 110));

To report bugs, see
.BR memusagestat (1),
.BR mtrace (1)
.BR (8)

Jan Chaloupka
* Software Engineer          *
* ENG Base Operating Systems *
* Red Hat Czech, s. r. o.    *
* UTC+1 (CET), jchaloup      *

Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]