libsheap
--------
Sheap Helps Examine Allocated Pointers

libsheap is a simple shared library to aid runtime heap analysis of an
application.  This library wraps malloc and free calls.  The allocated data
returned by the memory allocator is output as well as the amount of CPU cycles
between calls to the true, underlying malloc implementation.  If glibc's malloc,
ptmalloc2, is used the actual size, including the header malloc attaches to each
returned chunk is reported.  The size of a returned chunk is typically more than
that of what the user requests, as the extra size can help reduce fragmentation. 


Notes
-----
If glibc's malloc is not used, the behavior is undefined.  libsheap does some
special memory snooping to determine how much memory glibc's malloc truly
allocates, thus if glibc's malloc is not used, the reported "true size" is
undefined.

Special thanks to Google and stackoverflow.com where I learned about wrapping
routines in the GNU/Linux system.  Much of the wrapping code here was
paraphrased from Checker's answer to a post over at stackoverflow.com Thanks
Checkers!
<http://stackoverflow.com/questions/262439/create-a-wrapper-function-for-malloc-and-free-in-c>


Building
--------
From the top-level directory of libsheap run:
    ./configure
    make

Debugging mode can be enabled when configuring by using the following option:
    ./configure --enable-debug

libsheap also has a CPU cycle counter which counts the cycles it takes between
calls to the underlying (wrapped) malloc.  This implementation is not terribly
accurate as interrupts can occur between the start and return of that wrapped
malloc.  This feature can be enabled via configure as follows (it is enabled by
default): 
    ./configure --enable-cycle-counter

The cycle counter can also be disabled, which will just report values of '0'
cycles instead: 
    ./configure --disable-cycle-counter

There is no install target.  You can install this shared library where ever you
desire.


Usage
-----
For the wrapper library to actually analyze data it must be loaded before any
other libraries the to-be-analyzed binary might have.  To load the library
first, the 'LD_PRELOAD' environment variable should be set.  To do such from a
bash shell:
    export LD_PRELOAD=/path/to/libsheap.X.X.so

It might be more pleasing to set the variable just before loading the binary, as
loading it to the shell will wrap all mallocs called from binarys that execute
within that shell.  Wrapping just for the binary can be accomplished as follows
(in a bash environment):
    LD_PRELOAD=/path/to/libsheap.X.X.so ./some_binary_to_analyize


Thanks
------
Checkers on stackoverflow.com
The rest of 757labs (www.757labs.com)
GNU (www.gnu.org)


Contact / Project URL
---------------------
mattdavis9@gmail.com
www.757labs.com/projects/libsheap
