memleax(1)

🫶 memleax — bestie, your process is leaking and i'm gonna find out where 💅

okay so real talk: this is the manual page for memleax(1), a General Commands Manual situation, and it's literally the tool you want when a running process is being shady about its memory. let's get into it ✨

---

🌸 NAME 🌸

memleax — debugs memory leak of a running process. that's it. that's the whole job. no cap.

---

✨ SYNOPSIS ✨

memleax [options] target-pid

you give it options, you give it a pid, it does its thing. iconic behavior honestly.

---

💖 DESCRIPTION 💖

so memleax debugs memory leaks in a running process by attaching to it. it hooks the target process's invocation of memory allocation and free, and reports the memory blocks that live long enough as memory leak — in real time. it's giving surveillance but make it helpful. 👑

the default expire threshold is 10 seconds, BUT — and i cannot stress this enough — you should always set it yourself with the -e option according to your scenarios. the default is a starting point, not a personality.

here's the beautiful part: there is no need to recompile the program or restart the target process. none. zero. you just run memleax to monitor the target process, wait for the real-time memory leak report, and then kill it (e.g. by Ctrl+C) to stop monitoring. that's the whole flow, bestie. 🦋

one thing to know: memleax follows new threads, but not forked processes. so if you want to debug multiple processes, just run multiple memleax. one per process, like little bodyguards. 🫶

---

🎀 OPTIONS 🎀

okay so the golden rule from the manpage itself: you should always set -e according to your scenarios. while other options are good in most instances with default values. so -e is the main character here, and everyone else is supporting cast. 💅

• -e expire — specifies memory free expire threshold in seconds. default is 10. an allocated memory block is reported as memory leak if it lives longer than this. you should always set this according to your scenarios — fr fr. for example, if you are debugging an HTTP server with keepalive, and there are connections last for more than 5 minutes, you should set -e 360 to cover it. and if your program is expected to free every memory in 1 second, you should set -e 2 to get report in time. match the threshold to the vibe of your program. ⭐
• -d debug-info-file — specifies separate debug information file. 🍓
• -l backtrace-limit — specifies the limit of backtrace levels. less level, better performance. default is 50, which is also the max. so 50 is the ceiling, bestie, you cannot exceed it. 🔥
• -m memory-block-max — stop monitoring if there are so many expired memory block at a same CallStack. default is 1000. 💀
• -c call-stack-max — stop monitoring if there are so many CallStack with memory leak. default is 1000. 😭
• -h — print help and quit. the classic. 🎀
• -v — print version and quit. also the classic. 🌸

---

🌈 OUTPUT 🌈

the memory blocks that live longer than the threshold are showed as:

CallStack[3]: memory expires with 101 bytes, backtrace:
    0x00007fd322bd8220  libc-2.17.so  malloc()+0
    0x000000000040084e  test  foo()+14  foo.c:12
    0x0000000000400875  test  bar()+37  bar.c:20
    0x0000000000400acb  test  main()+364  test.c:80

CallStack[3] is the ID of CallStack where memory leak happens. that's your little tracking number, iykyk. 🔍

the backtrace is showed only on the first time, while it only shows the ID and counter if expiring again:

CallStack[3]: memory expires with 101 bytes, 2 times again

if the expired memory block is freed later, it shows:

CallStack[6]: expired-memory frees after 10 seconds

and if there are too many expired-memory-blocks freed on one CallStack, this CallStack will not be showed again:

Warning: too many expired-free at CallStack[6]. will not show
this CallStack later

when you think you have found the answer, stop the debug. that's the moment. the payoff. 🙈

okay so here's when memleax quits on you — take notes bestie: - you stop it, by Ctrl+C or kill, - the target process quits, - too many leaks at one CallStack (option -m), or - too many CallStacks with memory leak (option -c).

after quitting, it also gives statistics for the CallStacks with memory leak. the grand finale, the receipts, the full report card: 📊

CallStack[3]: may-leak=20 (2020 bytes)
    expired=20 (2020 bytes), free_expired=0 (0 bytes)
    alloc=20 (2020 bytes), free=0 (0 bytes)
    freed memory live time: min=0 max=0 average=0
    un-freed memory live time: max=20
    0x00007fd322bd8220  libc-2.17.so  malloc()+0
    0x000000000040084e  test  foo()+14  foo.c:12
    0x0000000000400875  test  bar()+37  bar.c:20
    0x0000000000400acb  test  main()+364  test.c:80

---

👑 AUTHOR 👑

written by Wu Bingzheng. 🫶

project GitHub: https://github.com/WuBingzheng/memleax

---

and that's the whole page, bestie!! this was memleax — version 1.1.1, dated 29 Jan 2017, living in the General Commands Manual. go find those leaks, you absolute icon. 🌟💜