.\" Copyright (c) 2013, Peter Schiffer <pschiffe@redhat.com>
.\" and Copyright (C) 2014, Michael Kerrisk <mtk.manpages@gmail.com>
.\"
.\" %%%LICENSE_START(GPLv2+_DOC_FULL)
.\" 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
.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
.\" 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
.\" <http://www.gnu.org/licenses/>.
.\" %%%LICENSE_END
.TH MEMUSAGE 1 2021-03-22 "GNU" "Linux user manual"
.SH NAME
memusage \- profile memory usage of a program
.SH SYNOPSIS
.nf
.BR memusage " [\fIoption\fR]... \fIprogram\fR [\fIprogramoption\fR]..."
.fi
.SH DESCRIPTION
.B memusage
is a bash script which profiles memory usage of the program,
.IR program .
It preloads the
.B libmemusage.so
library into the caller's environment (via the
.B LD_PRELOAD
environment variable; see
.BR ld.so (8)).
The
.B libmemusage.so
library traces memory allocation by intercepting calls to
.BR malloc (3),
.BR calloc (3),
.BR free (3),
and
.BR realloc (3);
optionally, calls to
.BR mmap (2),
.BR mremap (2),
and
.BR munmap (2)
can also be intercepted.
.PP
.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
.B memusage
contains three fields:
.RS 4
.TP
\fBheap total\fR
Sum of \fIsize\fR arguments of all
.BR malloc (3)
calls,
products of arguments (\fInmemb\fR*\fIsize\fR) of all
.BR calloc (3)
calls,
and sum of \fIlength\fR arguments of all
.BR mmap (2)
calls.
In the case of
.BR realloc (3)
and
.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.
.TP
.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),
and
\fInew_size\fR arguments of
.BR mremap (2).
.TP
.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.
.RE
.PP
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.
For
.BR realloc (3)
and
.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.
For
.BR realloc (3),
the additional field "free" shows reallocations that
caused a block to be freed (i.e., the reallocated size was 0).
.PP
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.
.SH OPTIONS
.TP
.BI \-n\  name \fR,\ \fB\-\-progname= name
Name of the program file to profile.
.TP
.BI \-p\  file \fR,\ \fB\-\-png= file
Generate PNG graphic and store it in
.IR file .
.TP
.BI \-d\  file \fR,\ \fB\-\-data= file
Generate binary data file and store it in
.IR file .
.TP
.B \-u\fR,\ \fB\-\-unbuffered
Do not buffer output.
.TP
.BI \-b\  size \fR,\ \fB\-\-buffer= size
Collect
.I size
entries before writing them out.
.TP
.B \-\-no\-timer
Disable timer-based
.RB ( SIGPROF )
sampling of stack pointer value.
.TP
.B \-m\fR,\ \fB\-\-mmap
Also trace
.BR mmap (2),
.BR mremap (2),
and
.BR munmap (2).
.TP
.B \-?\fR,\ \fB\-\-help
Print help and exit.
.TP
.B \-\-usage
Print a short usage message and exit.
.TP
.B \-V\fR,\ \fB\-\-version
Print version information and exit.
.TP
The following options apply only when generating graphical output:
.TP
.B \-t\fR,\ \fB\-\-time\-based
Use time (rather than number of function calls) as the scale for the X axis.
.TP
.B \-T\fR,\ \fB\-\-total
Also draw a graph of total memory use.
.TP
.BI \fB\-\-title= name
Use
.I name
as the title of the graph.
.TP
.BI \-x\  size \fR,\ \fB\-\-x\-size= size
Make the graph
.I size
pixels wide.
.TP
.BI \-y\  size \fR,\ \fB\-\-y\-size= size
Make the graph
.I size
pixels high.
.SH EXIT STATUS
The exit status of
.BR memusage
is equal to the exit status of the profiled program.
.SH BUGS
To report bugs, see
.UR http://www.gnu.org/software/libc/bugs.html
.UE
.SH EXAMPLES
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 :
.PP
.in +4n
.EX
$ \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
.EE
.in
.SS Program source
.EX
#include <stdio.h>
#include <stdlib.h>

#define CYCLES 20

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

    size = sizeof(*p) * 100;
    printf("malloc: %zu\en", size);
    p = malloc(size);

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

        size = sizeof(*p) * (j * 50 + 110);
        printf("realloc: %zu\en", size);
        p = realloc(p, size);

        size = sizeof(*p) * ((j + 1) * 150 + 110);
        printf("realloc: %zu\en", size);
        p = realloc(p, size);
    }

    free(p);
    exit(EXIT_SUCCESS);
}
.EE
.SH SEE ALSO
.BR memusagestat (1),
.BR mtrace (1),
.BR ld.so (8)