MEMUSAGE(1)							 Linux user manual						       MEMUSAGE(1)

NAME

       memusage - profile memory usage of a program

SYNOPSIS

       memusage [option]... program [programoption]...

DESCRIPTION

       memusage  is  a	bash script which profiles memory usage of the program, program.  It preloads the libmemusage.so library into the caller's
       environment (via the LD_PRELOAD environment variable; see ld.so(8)).  The libmemusage.so library traces memory allocation  by  intercepting
       calls to malloc(3), calloc(3), free(3), and realloc(3); optionally, calls to mmap(2), mremap(2), and munmap(2) can also be intercepted.

       memusage can output the collected data in textual form, or it can use memusagestat(1) (see the -p option,  below) to create a PNG file con-
       taining graphical representation of the collected data.

   Memory usage summary
       The "Memory usage summary" line output by memusage contains three fields:

	   heap total
		  Sum of size arguments of all malloc(3) calls, products of arguments (nmemb*size) of all calloc(3) calls, and sum of length argu-
		  ments of all mmap(2) calls.  In the case of realloc(3) and mremap(2), if the new size of an allocation is larger than the previ-
		  ous size, the sum of all such differences (new size minus old size) is added.

	   heap peak
		  Maximum of all size arguments of malloc(3), all products of nmemb*size of calloc(3), all size arguments  of  realloc(3),  length
		  arguments of mmap(2), and new_size arguments of mremap(2).

	   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.  For realloc(3) and 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 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 memusage does not reflect cases where 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.

   Histogram for block sizes
       The "Histogram for block sizes" provides a breakdown of memory allocations into various bucket sizes.

OPTIONS

       -n name, --progname=name
	      Name of the program file to profile.

       -p file, --png=file
	      Generate PNG graphic and store it in file.

       -d file, --data=file
	      Generate binary data file and store it in file.

       -u, --unbuffered
	      Do not buffer output.

       -b size, --buffer=size
	      Collect size entries before writing them out.

       --no-timer
	      Disable timer-based (SIGPROF) sampling of stack pointer value.

       -m, --mmap
	      Also trace mmap(2), mremap(2), and munmap(2).

       -?, --help
	      Print help and exit.

       --usage
	      Print a short usage message and exit.

       -V, --version
	      Print version information and exit.

       The following options apply only when generating graphical output:

       -t, --time-based
	      Use time (rather than number of function calls) as the scale for the X axis.

       -T, --total
	      Also draw a graph of total memory use.

       --title=name
	      Use name as the title of the graph.

       -x size, --x-size=size
	      Make the graph size pixels wide.

       -y size, --y-size=size
	      Make the graph size pixels high.

EXIT STATUS

       Exit status is equal to the exit status of profiled program.

BUGS

       To report bugs, see <http://www.gnu.org/software/libc/bugs.html>

EXAMPLE

       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 memusage.png:

	   $ memusage --data=memusage.dat ./a.out
	   ...
	   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% ================
	   $ memusagestat memusage.dat memusage.png

   Program source
       #include <stdio.h>
       #include <stdlib.h>

       #define CYCLES 20

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

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

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

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

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

	    free(p);
	    exit(EXIT_SUCCESS);
       }

SEE ALSO

       memusagestat(1), mtrace(1) ld.so(8)

COLOPHON

       This page is part of release 4.15 of the Linux man-pages project.  A description of the project, information about reporting bugs, and  the
       latest version of this page, can be found at https://www.kernel.org/doc/man-pages/.

GNU
								    2017-09-15							       MEMUSAGE(1)