# memusage - profile memory usage of a program - man(1) - [phpMan] [_memusage_(1)](https://www.chedong.com/phpMan.php/man/memusage/1/markdown) General Commands Manual [_memusage_(1)](https://www.chedong.com/phpMan.php/man/memusage/1/markdown) ## 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)](https://www.chedong.com/phpMan.php/man/ld.so/8/markdown)). The **libmemusage.so **library traces memory allocation by intercepting calls to [**malloc**(3)](https://www.chedong.com/phpMan.php/man/malloc/3/markdown), [**calloc**(3)](https://www.chedong.com/phpMan.php/man/calloc/3/markdown), [**free**(3)](https://www.chedong.com/phpMan.php/man/free/3/markdown), and [**realloc**(3)](https://www.chedong.com/phpMan.php/man/realloc/3/markdown); optionally, calls to [**mmap**(2)](https://www.chedong.com/phpMan.php/man/mmap/2/markdown), [**mremap**(2)](https://www.chedong.com/phpMan.php/man/mremap/2/markdown), and [**munmap**(2)](https://www.chedong.com/phpMan.php/man/munmap/2/markdown) can also be intercepted. **memusage **can output the collected data in textual form, or it can use [**memusagestat**(1)](https://www.chedong.com/phpMan.php/man/memusagestat/1/markdown) (see the **-p **option, below) to create a PNG file containing graphical representation of the col‐ lected 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)](https://www.chedong.com/phpMan.php/man/malloc/3/markdown) calls, products of arguments (_nmemb_*_size_) of all [**calloc**(3)](https://www.chedong.com/phpMan.php/man/calloc/3/markdown) calls, and sum of _length_ arguments of all [**mmap**(2)](https://www.chedong.com/phpMan.php/man/mmap/2/markdown) calls. In the case of [**realloc**(3)](https://www.chedong.com/phpMan.php/man/realloc/3/markdown) and [**mremap**(2)](https://www.chedong.com/phpMan.php/man/mremap/2/markdown), 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. **heap peak** Maximum of all _size_ arguments of [**malloc**(3)](https://www.chedong.com/phpMan.php/man/malloc/3/markdown), all products of _nmemb_*_size_ of **cal‐** [**loc**(3)](https://www.chedong.com/phpMan.php/man/loc/3/markdown), all _size_ arguments of [**realloc**(3)](https://www.chedong.com/phpMan.php/man/realloc/3/markdown), _length_ arguments of [**mmap**(2)](https://www.chedong.com/phpMan.php/man/mmap/2/markdown), and _new_size_ arguments of [**mremap**(2)](https://www.chedong.com/phpMan.php/man/mremap/2/markdown). **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 ad‐ dress is read and the difference from the base stack pointer computed. The maxi‐ mum of these differences is then the stack peak. Immediately following this summary line, a table shows the number calls, total memory allo‐ cated or deallocated, and number of failed calls for each intercepted function. For **real‐** [**loc**(3)](https://www.chedong.com/phpMan.php/man/loc/3/markdown) and [**mremap**(2)](https://www.chedong.com/phpMan.php/man/mremap/2/markdown), the additional field "nomove" shows reallocations that changed the ad‐ dress of a block, and the additional "dec" field shows reallocations that decreased the size of the block. For [**realloc**(3)](https://www.chedong.com/phpMan.php/man/realloc/3/markdown), 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 **real‐** [**loc**(3)](https://www.chedong.com/phpMan.php/man/loc/3/markdown) 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/to‐ tal memory" cell. ### Histogram for block sizes The "Histogram for block sizes" provides a breakdown of memory allocations into various bucket sizes. ## OPTIONS ### -n _ --progname=_ Name of the program file to profile. ### -p _ --png=_ Generate PNG graphic and store it in _file_. ### -d _ --data=_ Generate binary data file and store it in _file_. ### -u --unbuffered Do not buffer output. ### -b _ --buffer=_ Collect _size_ entries before writing them out. ### --no-timer Disable timer-based (**SIGPROF**) sampling of stack pointer value. ### -m --mmap Also trace [**mmap**(2)](https://www.chedong.com/phpMan.php/man/mmap/2/markdown), [**mremap**(2)](https://www.chedong.com/phpMan.php/man/mremap/2/markdown), and [**munmap**(2)](https://www.chedong.com/phpMan.php/man/munmap/2/markdown). **-?**, **--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 _ --x-size=_ Make the graph _size_ pixels wide. ### -y _ --y-size=_ Make the graph _size_ pixels high. ## EXIT STATUS The exit status of **memusage **is equal to the exit status of the profiled program. ## BUGS To report bugs, see []() ## 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 _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 #include #define CYCLES 20 int main(int argc, char *argv[]) { int i, j; size_t size; int *p; size = sizeof(*p) * 100; printf("malloc: %zu\n", 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\n", size); p = realloc(p, size); size = sizeof(*p) * ((j + 1) * 150 + 110); printf("realloc: %zu\n", size); p = realloc(p, size); } free(p); exit(EXIT_SUCCESS); } ## SEE ALSO [**memusagestat**(1)](https://www.chedong.com/phpMan.php/man/memusagestat/1/markdown), [**mtrace**(1)](https://www.chedong.com/phpMan.php/man/mtrace/1/markdown), [**ld.so**(8)](https://www.chedong.com/phpMan.php/man/ld.so/8/markdown) Linux man-pages 6.7 2023-10-31 [_memusage_(1)](https://www.chedong.com/phpMan.php/man/memusage/1/markdown)