README

This is a small memory leak tracer for C programs. It is much faster than the
heap checker built into glibc or tcmalloc, 5-8x faster typically. It will not
detect any other type of malloc errors besides memory leaks, so this won't
help you if you have other memory issues.

It uses libunwind to retrieve stack traces for each allocation. Stack traces
are prepended to the malloc'd memory blocks, to avoid needing a separate data
structure to track alloc'd and free'd stack traces. This obviously increases
the amount of memory being used by the application, but it's overall
insignificant. Storing this way also allows the tracer to stash its info
without requiring use of any mutexes in threaded code.

Output is generated by an atexit() handler, so your program must exit cleanly
in order to get any results. The output is a binary file containing a list of
all of the unfreed blocks and the stack trace where they were allocated. The
mdump tool is provided for reading this data and generating a text report of
the leaks. The dumper uses libbfd to look up symbol names.

You must have both libunwind and libbfd to build this code. Most of the code
is portable to generic POSIX but the scan for heap space is Linux-specific.
Also, code for reading the linker map uses the Linux convention of
dlopen(NULL) to get a handle to the current program. Most POSIX systems let
you use RTLD_SELF instead but for some reason glibc stopped supporting this
many years ago.

To use the tracer:
	make
	cp mleak.so mdump /tmp
	LD_PRELOAD=/tmp/mleak.so my_buggy_program
	/tmp/mdump my_buggy_program ml.*

The mleak.so wrapper generates two output files: ml.info, which contains the
map of dynamically loaded objects and ml.data, which contains the record of
leaked memory blocks. The mdump program reads both of these files to produce
its report.

 -- Howard Chu 2015-03-24


Snapshot feature: send a SIGPROF to the traced program, to get a dump of the
memory in use at that time. Note that there is no thread locking protection
on this action so your program should be idle when you send it the signal.
The ml.data and ml.info files will be generated, and can be processed using
mdump. Diffing the output from successive snapshots will let you see how
memory use changes over time.

 -- Howard Chu 2016-12-26