University of California at Berkeley
           Department of Electrical Engineering & Computer Sciences
                   Instructional & Electronics Support Groups

 						                   
/share/b/pub/efence.help
								   Apr 26, 2002

		      Electric Fence Memory Leak Debugger


efence, short for Electric Fence, consists of the library libefence.a that you
link with your program to detect memory leaks.  The library is installed in 
/usr/sww/lib/libefence.a for Solaris SPARC and X86 computers.

INSTRUCTIONS FOR DEBUGGING YOUR PROGRAM

     1.   Link with libefence.a as explained above:
          gcc -g -lefence -o example  example.c

     2.   Run your program in a debugger and fix any overruns  or
          accesses to free memory:
          gdb  example

     3.   Quit the debugger.

     4.   Set EF_PROTECT_BELOW = 1 in the shell environment:
          setenv EF_PROTECT_BELOW  1 
          OR  
          EF_PROTECT_BELOW=1; export  EF_PROTECT_BELOW   (bash syntax)

     5.   Repeat step 2, this time repairing  underruns  if  they
          occur.

     6.   Quit the debugger.

To get the manual page, type either

	man libefence
	man -M /usr/sww/pkg/electricfence libefence

USAGE:

     Link your program with the library libefence.a .  Make sure you are not 
     linking with -lmalloc, -lmallocdebug, or with other malloc-debugger or 
     malloc-enhancer libraries.  You can only use one at a time. You should 
     use the -lefence argument to the linker, otherwise you'll have to put 
     the path-name /usr/sww/lib for libefence.a in the linker's command line.  
     Some systems will require special arguments to the linker to assure that 
     you are using the Electric Fence malloc() and not the one from your C 
     library.

     Run your program using a debugger.  It's easier to work this way than to  
     create a core file and post-mortem debug it.  Electric Fence can create 
     huge core files, and some operating systems will thus take minutes 
     simply to dump core!  Some operating systems will not create usable core 
     files from programs that are linked with Electric Fence.  If your pro-
     gram has one of the errors detected by  Electric Fence, it will get a  
     segmentation  fault (SIGSEGV) at the offending instruction.   Use the 
     debugger to locate the erroneous statement, and repair it.

     libefence should not be used in a production environment, because it slows 
     down your program quite a bit and increases the memory requirements.


Send questions about 349 Soda to "inst@eecs.berkeley.edu".

					Instructional & Electronics Support
					384/386 Cory, 333 Soda
					inst@eecs.berkeley.edu