memusage(1)

💖 memusage — from the memusage(1) page, General Commands Manual energy 💖

okay bestie, sit DOWN, because this little script is about to tell you exactly how much memory your program is gulping 🍓

---

✨ NAME ✨

memusage — profile memory usage of a program 👑

---

🌸 SYNOPSIS 🌸

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

---

🦋 DESCRIPTION 🦋

So like. memusage is a bash(1) script, right? and its whole thing is profiling the memory usage of the program program. the way it does this is SO clever — it preloads the libmemusage.so library into the caller's environment (through the LD_PRELOAD environment variable, peep ld.so(8) for the deets). 💅

then libmemusage.so traces memory allocation by intercepting calls to malloc(3), calloc(3), free(3), and realloc(3). and if you want more? optionally it can also intercept calls to mmap(2), mremap(2), and munmap(2). obsessed.

memusage can spit the collected data out as plain text, OR it can hand things off to memusagestat(1) (that's the -p option, scroll down bestie) to make a PNG file with a whole graphical representation of all that collected data. main character behaviour, honestly. ✨

---

🌈 Memory usage summary 🌈

the "Memory usage summary" line that memusage outputs has three fields, and yes you need to know all three:

• heap total — the sum of size arguments of all malloc(3) calls, plus the products of arguments (n*size) of all calloc(3) calls, plus the sum of length arguments of all mmap(2) calls. and for realloc(3) and mremap(2)? if the new size of an allocation is bigger than the previous size, then the sum of all those differences (new size minus old size) gets added in. math is mathing. 🧮
• heap peak — the maximum of all size arguments of malloc(3), all products of n*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 (that's the base stack pointer) gets saved. after each function call, the actual stack pointer address is read and the difference from the base stack pointer is computed. the maximum of all those differences? that's your stack peak. 🎀

and IMMEDIATELY after that summary line, there's a table showing the number calls, total memory allocated or deallocated, and number of failed calls for each intercepted function. for realloc(3) and mremap(2) there's an extra field "nomove" which shows reallocations that changed the address of a block, plus an extra "dec" field showing reallocations that decreased the size of the block. and for realloc(3), there's one more extra field "free" that shows reallocations which caused a block to be freed (like, the reallocated size was 0). 🫶

⚠️ heads up bestie, this part matters: the "realloc/total memory" of the table that memusage outputs does not reflect cases where realloc(3) is used to reallocate a block of memory to have a smaller size than previously. this can make the sum of all "total memory" cells (excluding "free") come out larger than the "free/total memory" cell. it's giving math that doesn't add up and that's just how it is, no cap. 💀

---

🧚 Histogram for block sizes 🧚

the "Histogram for block sizes" gives you a breakdown of memory allocations into various bucket sizes. little buckets, filling up with your memory. adorable. 🌸

---

💅 OPTIONS 💅

• -n name, --progname=name — name of the program file to profile.
• -p file, --png=file — generate a PNG graphic and store it in file.
• -d file, --data=file — generate a 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 the 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.

and these next ones? they only apply when you're generating graphical output, iykyk: 🎨

• -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 🔥

the exit status of memusage is equal to the exit status of the profiled program. simple as that, periodt.

---

😭 BUGS 😭

to report bugs, see http://www.gnu.org/software/libc/bugs.html

(not me telling you where to file the bug reports, go off 🫶)

---

⭐ 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 <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\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), mtrace(1), ld.so(8)

---

and that's the whole thing bestie!! this page came from Linux man-pages 6.20, dated 2026-02-08 — so you know it's fresh. go profile something, you absolute legend 💖✨🦋🌈👑