path: root/libraries/electric-fence/README

Electric Fence is a debugger that uses virtual memory hardware to detect
illegal memory accesses. It can detect two common programming bugs:
software that overruns or underruns the boundaries of a malloc() memory
allocation, and software that touches a memory allocation that has been
released by free().

Unlike other malloc() debuggers, Electric Fence will detect read accesses
as well as writes, and it will stop and pinpoint the exact instruction
that causes an error. It is not as thorough as Purify, however.

In order to debug a program it needs to be linked with Electric Fence's
library or dynamic linking needs to be used; README.Debian explains that
in detail.

In addition to the static library (libefence.a), this package also
contains a shared library of electric fence (libefence.so). Thus, you
don't need to recompile your programs any more, all you need to do is:

LD_PRELOAD=libefence.so ./your-buggy-program

and libefence's malloc will be used.

If you're using c++, and you and want to statically link your c++
programs, you shouldn't use g++ to link libefence.a, but rather:
    gcc -o myprog myprog.o -lstdc++ -lg++ -lefence
(if you use g++, the order is different, and efence's malloc doesn't
get used)

Be sure to read the `libefence` manpage which describes how to set
various environment variables which alter lebefence's behavior