{ "content": [ { "type": "text", "text": "# memusage (man)\n\n## NAME\n\nmemusage - profile memory usage of a program\n\n## SYNOPSIS\n\nmemusage [option]... program [programoption]...\n\n## DESCRIPTION\n\nmemusage is a bash script which profiles memory usage of the program, program. It preloads\nthe libmemusage.so library into the caller's environment (via the LDPRELOAD environment\nvariable; see ld.so(8)). The libmemusage.so library traces memory allocation by intercepting\ncalls to malloc(3), calloc(3), free(3), and realloc(3); optionally, calls to mmap(2),\nmremap(2), and munmap(2) can also be intercepted.\n\n## Sections\n\n- **NAME**\n- **SYNOPSIS**\n- **DESCRIPTION** (2 subsections)\n- **OPTIONS** (13 subsections)\n- **EXIT STATUS**\n- **BUGS**\n- **EXAMPLES** (1 subsections)\n- **SEE ALSO**\n- **COLOPHON**\n\nUse structuredContent.sections for detailed options, examples, and full documentation.\n" } ], "structuredContent": { "command": "memusage", "section": "", "mode": "man", "summary": "memusage - profile memory usage of a program", "synopsis": "memusage [option]... program [programoption]...", "tldr_summary": null, "tldr_examples": [], "tldr_source": null, "flags": [ { "flag": "-n", "long": null, "arg": null, "description": "Name of the program file to profile." }, { "flag": "-p", "long": null, "arg": null, "description": "Generate PNG graphic and store it in file." }, { "flag": "-d", "long": null, "arg": null, "description": "Generate binary data file and store it in file." }, { "flag": "-u", "long": "--unbuffered", "arg": null, "description": "Do not buffer output." }, { "flag": "-b", "long": null, "arg": null, "description": "Collect size entries before writing them out." }, { "flag": "", "long": "--no-timer", "arg": null, "description": "Disable timer-based (SIGPROF) sampling of stack pointer value." }, { "flag": "-m", "long": "--mmap", "arg": null, "description": "Also trace mmap(2), mremap(2), and munmap(2). -?, --help Print help and exit." }, { "flag": "", "long": "--usage", "arg": null, "description": "Print a short usage message and exit." }, { "flag": "-V", "long": "--version", "arg": null, "description": "Print version information and exit. The following options apply only when generating graphical output:" }, { "flag": "-t", "long": "--time-based", "arg": null, "description": "Use time (rather than number of function calls) as the scale for the X axis." }, { "flag": "-T", "long": "--total", "arg": null, "description": "Also draw a graph of total memory use. --title=name Use name as the title of the graph." }, { "flag": "-x", "long": null, "arg": null, "description": "Make the graph size pixels wide." }, { "flag": "-y", "long": null, "arg": null, "description": "Make the graph size pixels high." } ], "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", "#include ", "#include ", "#define CYCLES 20", "int", "main(int argc, char *argv[])", "int i, j;", "sizet 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(EXITSUCCESS);" ], "see_also": [ { "name": "memusagestat", "section": "1", "url": "https://www.chedong.com/phpMan.php/man/memusagestat/1/json" }, { "name": "mtrace", "section": "1", "url": "https://www.chedong.com/phpMan.php/man/mtrace/1/json" }, { "name": "ld.so", "section": "8", "url": "https://www.chedong.com/phpMan.php/man/ld.so/8/json" } ], "section_outline": [ { "name": "NAME", "lines": 2, "subsections": [] }, { "name": "SYNOPSIS", "lines": 2, "subsections": [] }, { "name": "DESCRIPTION", "lines": 10, "subsections": [ { "name": "Memory usage summary", "lines": 32 }, { "name": "Histogram for block sizes", "lines": 3 } ] }, { "name": "OPTIONS", "lines": 1, "subsections": [ { "name": "-n --progname=", "lines": 2, "flag": "-n" }, { "name": "-p --png=", "lines": 2, "flag": "-p" }, { "name": "-d --data=", "lines": 2, "flag": "-d" }, { "name": "-u --unbuffered", "lines": 2, "flag": "-u", "long": "--unbuffered" }, { "name": "-b --buffer=", "lines": 2, "flag": "-b" }, { "name": "--no-timer", "lines": 2, "long": "--no-timer" }, { "name": "-m --mmap", "lines": 5, "flag": "-m", "long": "--mmap" }, { "name": "--usage", "lines": 2, "long": "--usage" }, { "name": "-V --version", "lines": 4, "flag": "-V", "long": "--version" }, { "name": "-t --time-based", "lines": 2, "flag": "-t", "long": "--time-based" }, { "name": "-T --total", "lines": 5, "flag": "-T", "long": "--total" }, { "name": "-x --x-size=", "lines": 2, "flag": "-x" }, { "name": "-y --y-size=", "lines": 2, "flag": "-y" } ] }, { "name": "EXIT STATUS", "lines": 2, "subsections": [] }, { "name": "BUGS", "lines": 2, "subsections": [] }, { "name": "EXAMPLES", "lines": 27, "subsections": [ { "name": "Program source", "lines": 35 } ] }, { "name": "SEE ALSO", "lines": 2, "subsections": [] }, { "name": "COLOPHON", "lines": 7, "subsections": [] } ], "sections": { "NAME": { "content": "memusage - profile memory usage of a program\n", "subsections": [] }, "SYNOPSIS": { "content": "memusage [option]... program [programoption]...\n", "subsections": [] }, "DESCRIPTION": { "content": "memusage is a bash script which profiles memory usage of the program, program. It preloads\nthe libmemusage.so library into the caller's environment (via the LDPRELOAD environment\nvariable; see ld.so(8)). The libmemusage.so library traces memory allocation by intercepting\ncalls to malloc(3), calloc(3), free(3), and realloc(3); optionally, calls to mmap(2),\nmremap(2), and munmap(2) can also be intercepted.\n\nmemusage can output the collected data in textual form, or it can use memusagestat(1) (see\nthe -p option, below) to create a PNG file containing graphical representation of the col‐\nlected data.\n", "subsections": [ { "name": "Memory usage summary", "content": "The \"Memory usage summary\" line output by memusage contains three fields:\n\nheap total\nSum of size arguments of all malloc(3) calls, products of arguments (nmemb*size)\nof all calloc(3) calls, and sum of length arguments of all mmap(2) calls. In the\ncase of realloc(3) and mremap(2), if the new size of an allocation is larger than\nthe previous size, the sum of all such differences (new size minus old size) is\nadded.\n\nheap peak\nMaximum of all size arguments of malloc(3), all products of nmemb*size of cal‐‐\nloc(3), all size arguments of realloc(3), length arguments of mmap(2), and\nnewsize arguments of mremap(2).\n\nstack peak\nBefore the first call to any monitored function, the stack pointer address (base\nstack pointer) is saved. After each function call, the actual stack pointer ad‐\ndress is read and the difference from the base stack pointer computed. The maxi‐\nmum of these differences is then the stack peak.\n\nImmediately following this summary line, a table shows the number calls, total memory allo‐\ncated or deallocated, and number of failed calls for each intercepted function. For real‐‐\nloc(3) and mremap(2), the additional field \"nomove\" shows reallocations that changed the ad‐\ndress of a block, and the additional \"dec\" field shows reallocations that decreased the size\nof the block. For realloc(3), the additional field \"free\" shows reallocations that caused a\nblock to be freed (i.e., the reallocated size was 0).\n\nThe \"realloc/total memory\" of the table output by memusage does not reflect cases where real‐‐\nloc(3) is used to reallocate a block of memory to have a smaller size than previously. This\ncan cause sum of all \"total memory\" cells (excluding \"free\") to be larger than the \"free/to‐\ntal memory\" cell.\n" }, { "name": "Histogram for block sizes", "content": "The \"Histogram for block sizes\" provides a breakdown of memory allocations into various\nbucket sizes.\n" } ] }, "OPTIONS": { "content": "", "subsections": [ { "name": "-n --progname=", "content": "Name of the program file to profile.\n", "flag": "-n" }, { "name": "-p --png=", "content": "Generate PNG graphic and store it in file.\n", "flag": "-p" }, { "name": "-d --data=", "content": "Generate binary data file and store it in file.\n", "flag": "-d" }, { "name": "-u --unbuffered", "content": "Do not buffer output.\n", "flag": "-u", "long": "--unbuffered" }, { "name": "-b --buffer=", "content": "Collect size entries before writing them out.\n", "flag": "-b" }, { "name": "--no-timer", "content": "Disable timer-based (SIGPROF) sampling of stack pointer value.\n", "long": "--no-timer" }, { "name": "-m --mmap", "content": "Also trace mmap(2), mremap(2), and munmap(2).\n\n-?, --help\nPrint help and exit.\n", "flag": "-m", "long": "--mmap" }, { "name": "--usage", "content": "Print a short usage message and exit.\n", "long": "--usage" }, { "name": "-V --version", "content": "Print version information and exit.\n\nThe following options apply only when generating graphical output:\n", "flag": "-V", "long": "--version" }, { "name": "-t --time-based", "content": "Use time (rather than number of function calls) as the scale for the X axis.\n", "flag": "-t", "long": "--time-based" }, { "name": "-T --total", "content": "Also draw a graph of total memory use.\n\n--title=name\nUse name as the title of the graph.\n", "flag": "-T", "long": "--total" }, { "name": "-x --x-size=", "content": "Make the graph size pixels wide.\n", "flag": "-x" }, { "name": "-y --y-size=", "content": "Make the graph size pixels high.\n", "flag": "-y" } ] }, "EXIT STATUS": { "content": "Exit status is equal to the exit status of profiled program.\n", "subsections": [] }, "BUGS": { "content": "To report bugs, see ⟨http://www.gnu.org/software/libc/bugs.html⟩\n", "subsections": [] }, "EXAMPLES": { "content": "Below is a simple program that reallocates a block of memory in cycles that rise to a peak\nbefore then cyclically reallocating the memory in smaller blocks that return to zero. After\ncompiling the program and running the following commands, a graph of the memory usage of the\nprogram can be found in the file memusage.png:\n\n$ memusage --data=memusage.dat ./a.out\n...\nMemory usage summary: heap total: 45200, heap peak: 6440, stack peak: 224\ntotal calls total memory failed calls\nmalloc| 1 400 0\nrealloc| 40 44800 0 (nomove:40, dec:19, free:0)\ncalloc| 0 0 0\nfree| 1 440\nHistogram for block sizes:\n192-207 1 2% ================\n...\n2192-2207 1 2% ================\n2240-2255 2 4% =================================\n2832-2847 2 4% =================================\n3440-3455 2 4% =================================\n4032-4047 2 4% =================================\n4640-4655 2 4% =================================\n5232-5247 2 4% =================================\n5840-5855 2 4% =================================\n6432-6447 1 2% ================\n$ memusagestat memusage.dat memusage.png\n", "subsections": [ { "name": "Program source", "content": "#include \n#include \n\n#define CYCLES 20\n\nint\nmain(int argc, char *argv[])\n{\nint i, j;\nsizet size;\nint *p;\n\nsize = sizeof(*p) * 100;\nprintf(\"malloc: %zu\\n\", size);\np = malloc(size);\n\nfor (i = 0; i < CYCLES; i++) {\nif (i < CYCLES / 2)\nj = i;\nelse\nj--;\n\nsize = sizeof(*p) * (j * 50 + 110);\nprintf(\"realloc: %zu\\n\", size);\np = realloc(p, size);\n\nsize = sizeof(*p) * ((j + 1) * 150 + 110);\nprintf(\"realloc: %zu\\n\", size);\np = realloc(p, size);\n}\n\nfree(p);\nexit(EXITSUCCESS);\n}\n" } ] }, "SEE ALSO": { "content": "memusagestat(1), mtrace(1), ld.so(8)\n", "subsections": [] }, "COLOPHON": { "content": "This page is part of release 5.10 of the Linux man-pages project. A description of the\nproject, information about reporting bugs, and the latest version of this page, can be found\nat https://www.kernel.org/doc/man-pages/.\n\n\n\nGNU 2020-11-01 MEMUSAGE(1)", "subsections": [] } } } }