Skip site navigation (1)Skip section navigation (2)

FreeBSD Man Pages

Man Page or Keyword Search:
Man Architecture
Apropos Keyword Search (all sections) Output format
home | help
efence(3)							     efence(3)

NAME
       efence -	Electric Fence Malloc Debugger

SYNOPSIS
       #include	<stdlib.h>

       void * malloc (size_t size);

       void free (void *ptr);

       void * realloc (void *ptr, size_t size);

       void * calloc (size_t nelem, size_t elsize);

       void * memalign (size_t alignment, size_t size);

       void * valloc (size_t size);

       extern int EF_ALIGNMENT;

       extern int EF_PROTECT_BELOW;

       extern int EF_PROTECT_FREE;

       extern int EF_ALLOW_MALLOC_0;

       extern int EF_FILL;

DESCRIPTION
       Electric	 Fence	helps you detect two common programming	bugs: software
       that overruns the boundaries of a malloc() memory allocation, and soft-
       ware 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	pinpoint the exact instruction
       that causes an error. It	has been in use	at Pixar since	1987,  and  at
       many other sites	for years.

       Electric	 Fence	uses  the  virtual memory hardware of your computer to
       place an	inaccessible memory page immediately after (or before, at  the
       user's  option)	each  memory allocation. When software reads or	writes
       this inaccessible page, the hardware issues a segmentation fault, stop-
       ping  the  program  at the offending instruction. It is then trivial to
       find the	erroneous statement using your favorite	debugger. In a similar
       manner,	memory	that has been released by free() is made inaccessible,
       and any code that touches it will get a segmentation fault.

       Simply linking your application with  libefence.a  will	allow  you  to
       detect  most,  but not all, malloc buffer overruns and accesses of free
       memory.	If you want to be reasonably sure that you've found  all  bugs
       of  this	 type, you'll have to read and understand the rest of this man
       page.

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.   If  your
       system  administrator  has  installed  Electric	Fence  for public use,
       you'll be able to use the -lefence argument to  the  linker,  otherwise
       you'll  have  to	put the	path-name for libefence.a in the linker's com-
       mand line.  You can also	use dynamic linking. If	you're using a	Bourne
       shell,  the  statement  export  LD_PRELOAD=libefence.so.0.0  will cause
       Electric	Fence to be loaded to run all dynamic executables.   The  com-
       mand ef command runs a single command under Electric Fence.

       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 cre-
       ate  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.

GLOBAL AND ENVIRONMENT VARIABLES
       Electric	Fence has four configuration switches that can be enabled  via
       the  shell environment, or by setting the value of global integer vari-
       ables using a debugger. These switches change what bugs Electric	 Fence
       will detect, so it's important that you know how	to use them.

       EF_ALIGNMENT
	      This  is	an integer that	specifies the alignment	for any	memory
	      allocations that will be returned	 by  malloc(),	calloc(),  and
	      realloc().   The	value is specified in bytes, thus a value of 4
	      will cause memory	to be aligned to 32-bit	boundaries unless your
	      system  doesn't  have a 8-bit characters.	EF_ALIGNMENT is	set to
	      sizeof(int) by default, since that is generally the word-size of
	      your  CPU.  If your program requires that	allocations be aligned
	      to 64-bit	boundaries and you have	a 32-bit int  you'll  have  to
	      set  this	 value	to 8. This is the case when compiling with the
	      -mips2 flag on MIPS-based	systems	such as	those from  SGI.   The
	      memory allocation	that is	returned by Electric Fence malloc() is
	      aligned using the	value in EF_ALIGNMENT, and its size the	multi-
	      ple of that value	that is	greater	than or	equal to the requested
	      size.  For this reason, you will sometimes want to set EF_ALIGN-
	      MENT  to	0  (no	alignment), so that you	can detect overruns of
	      less than	your CPU's word	size. Be  sure	to  read  the  section
	      WORD-ALIGNMENT  AND OVERRUN DETECTION in this manual page	before
	      you try this.  To	change this value,  set	 EF_ALIGNMENT  in  the
	      shell  environment  to an	integer	value, or assign to the	global
	      integer variable EF_ALIGNMENT using a debugger.

       EF_PROTECT_BELOW
	      Electric Fence usually places an inaccessible  page  immediately
	      after  each  memory  allocation, so that software	that runs past
	      the end of the allocation	 will  be  detected.  Setting  EF_PRO-
	      TECT_BELOW  to 1 causes Electric Fence to	place the inaccessible
	      page before the allocation in the	address	space, so that	under-
	      runs  will  be  detected	instead	 of  over-runs.	  When EF_PRO-
	      TECT_BELOW is set, the EF_ALIGNMENT parameter is	ignored.   All
	      allocations  will	 be aligned to virtual-memory-page boundaries,
	      and their	size will be the exact size that  was  requested.   To
	      change this value, set EF_PROTECT_BELOW in the shell environment
	      to an integer value, or assign to	the  global  integer  variable
	      EF_PROTECT_BELOW using a debugger.

       EF_PROTECT_FREE
	      Electric	Fence usually returns free memory to a pool from which
	      it may be	re-allocated. If you suspect that  a  program  may  be
	      touching	free memory, set EF_PROTECT_FREE to 1. This will cause
	      Electric Fence to	never re-allocate  memory  once	 it  has  been
	      freed,  so that any access to free memory	will be	detected. Some
	      programs will use	tremendous amounts of memory when this parame-
	      ter  is  set.   To change	this value, set	EF_PROTECT_FREE	in the
	      shell environment	to an integer value, or	assign to  the	global
	      integer variable EF_PROTECT_FREE using a debugger.

       EF_ALLOW_MALLOC_0
	      By  default,  Electric Fence traps calls to malloc() with	a size
	      of zero, because they are	often the result of a software bug. If
	      EF_ALLOW_MALLOC_0	 is non-zero, the software will	not trap calls
	      to malloc() with a size of zero.	 To  change  this  value,  set
	      EF_ALLOC_MALLOC_0	 in the	shell environment to an	integer	value,
	      or assign	to the global integer variable EF_ALLOC_MALLOC_0 using
	      a	debugger.

       EF_FILL
	      When  set	 to a value between 0 and 255, every byte of allocated
	      memory is	initialized to that value. This	can help detect	 reads
	      of  uninitialized	memory.	 When set to -1, some memory is	filled
	      with zeroes (the operating system	default	on most	 systems)  and
	      some memory will retain the values written to it during its last
	      use.

WORD-ALIGNMENT AND OVERRUN DETECTION
       There is	a conflict between the alignment  restrictions	that  malloc()
       operates	 under and the debugging strategy used by Electric Fence. When
       detecting overruns, Electric Fence malloc() allocates two or more  vir-
       tual memory pages for each allocation. The last page is made inaccessi-
       ble in such a way that any read,	write, or execute access will cause  a
       segmentation  fault.   Then,  Electric  Fence  malloc()	will return an
       address such that the first byte	after the end of the allocation	is  on
       the  inaccessible page.	Thus, any overrun of the allocation will cause
       a segmentation fault.

       It follows that the address returned by malloc()	is the address of  the
       inaccessible  page  minus  the size of the memory allocation.  Unfortu-
       nately, malloc()	is required to return word-aligned allocations,	 since
       many CPUs can only access a word	when its address is aligned.  The con-
       flict happens when software makes a memory allocation using a size that
       is  not a multiple of the word size, and	expects	to do word accesses to
       that allocation.	The location of	the  inaccessible  page	 is  fixed  by
       hardware	 at  a	word-aligned address. If Electric Fence	malloc() is to
       return an aligned address, it must increase the size of the  allocation
       to  a multiple of the word size.	 In addition, the functions memalign()
       and valloc() must honor explicit	specifications on the alignment	of the
       memory  allocation,  and	 this,	as  well  can  only  be	implemented by
       increasing the size of the allocation.  Thus, there will	be  situations
       in  which  the  end of a	memory allocation contains some	padding	space,
       and accesses of that padding space will not be detected,	even  if  they
       are overruns.

       Electric	 Fence provides	the variable EF_ALIGNMENT so that the user can
       control the default alignment used by  malloc(),	 calloc(),  and	 real-
       loc().	To  debug  overruns  as	 small	as  a single byte, you can set
       EF_ALIGNMENT to zero. This  will	 result	 in  Electric  Fence  malloc()
       returning unaligned addresses for allocations with sizes	that are not a
       multiple	of the word size. This is not a	problem	in most	cases, because
       compilers  must	pad the	size of	objects	so that	alignment restrictions
       are honored when	storing	those objects in arrays. The problem  surfaces
       when  software  allocates  odd-sized  buffers  for objects that must be
       word-aligned. One case of this is software that allocates a  buffer  to
       contain	a structure and	a string, and the string has an	odd size (this
       example was in a	popular	TIFF library). If word references are made  to
       un-aligned buffers, you will see	a bus error (SIGBUS) instead of	a seg-
       mentation fault.	The only way to	fix this is to re-write	the  offending
       code  to	 make byte references or not make odd-sized allocations, or to
       set EF_ALIGNMENT	to the word size.

       Another example of software incompatible	with EF_ALIGNMENT <  word-size
       is the strcmp() function	and other string functions on SunOS (and prob-
       ably Solaris), which make word-sized accesses to	character strings, and
       may  attempt  to	 access	 up to three bytes beyond the end of a string.
       These result in a segmentation fault (SIGSEGV).	The  only  way	around
       this  is	to use versions	of the string functions	that perform byte ref-
       erences instead of word references.

INSTRUCTIONS FOR DEBUGGING YOUR	PROGRAM
       1.     Link with	libefence.a as explained above.

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

       3.     Quit the debugger.

       4.     Set EF_PROTECT_BELOW = 1 in the shell environment.

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

       6.     Quit the debugger.

       7.     Read the restrictions in the section on WORD-ALIGNMENT AND OVER-
	      RUN DETECTION.  See if you can set EF_ALIGNMENT to 0 and	repeat
	      step  2.	Sometimes this will be too much	work, or there will be
	      problems with library routines for  which	 you  don't  have  the
	      source, that will	prevent	you from doing this.

MEMORY USAGE AND EXECUTION SPEED
       Since Electric Fence uses at least two virtual memory pages for each of
       its allocations,	it's a terrible	memory hog. I've  sometimes  found  it
       necessary  to  add a swap file using swapon(8) so that the system would
       have enough virtual memory to debug my program. Also, the way we	manip-
       ulate  memory  results  in various cache	and translation	buffer entries
       being flushed with each call to malloc or free. The end result is  that
       your  program  will be much slower and use more resources while you are
       debugging it with Electric Fence.

       Don't leave libefence.a linked into production software!	 Use  it  only
       for debugging.

MAILING	LIST
       There  is  a  mailing list to support Electric Fence. You can subscribe
       using the mail form  at	http://lists.perens.com/mailman/listinfo/elec-
       tric-fence .

AUTHOR
       Bruce Perens

WARNINGS
       I have tried to do as good a job	as I can on this software, but I doubt
       that it is even theoretically possible to make it bug-free.  This soft-
       ware  has  no  warranty.	 It  will  not detect some bugs	that you might
       expect it to detect, and	will indicate that some	non-bugs are bugs.

LICENSE
       Copyright 1987-1999 Bruce Perens. All rights reserved.
       This program is free software; you can redistribute it and/or modify it
       under  the  terms of the	GNU General Public License, Version 2, as pub-
       lished by the Free Software Foundation. A copy of this license is  dis-
       tributed	with this software in the file "COPYING".

       This  program  is  distributed  in the hope that	it will	be useful, but
       WITHOUT ANY  WARRANTY;  without	even  the  implied  warranty  of  MER-
       CHANTABILITY  or	FITNESS	FOR A PARTICULAR PURPOSE. Read the file	"COPY-
       ING" for	more details.

CONTACTING THE AUTHOR
       Bruce Perens
       1563 Solano Ave.	#349
       Berkeley, CA 94707
       Telephone: 510-526-1165
       Internet: bruce@perens.com

FILES
       /dev/zero: Source of memory pages (via mmap(2)).

SEE ALSO
       malloc(3), mmap(2), mprotect(2),	swapon(8)

DIAGNOSTICS
       Segmentation Fault: Examine the offending statement  for	 violation  of
       the boundaries of a memory allocation.
       Bus Error: See the section on WORD-ALIGNMENT AND	OVERRUN	DETECTION.  in
       this manual page.

BUGS
       My explanation of the alignment issue could be improved.

       Some Sun	systems	running	SunOS 4.1 were reported	to signal an access to
       a  protected page with SIGBUS rather than SIGSEGV, I suspect this is an
       undocumented feature of a particular Sun	hardware version, not just the
       operating  system.  On these systems, eftest will fail with a bus error
       until you modify	the Makefile to	define PAGE_PROTECTION_VIOLATED_SIGNAL
       as SIGBUS.

       There are, without doubt, other bugs and	porting	issues.	Please contact
       me via e-mail if	you have any bug reports, ideas, etc.

WHAT'S BETTER
       Purify does a much more thorough	job than Electric Fence, and does  not
       have  the  huge memory overhead.	 Checkergcc, a modified	version	of the
       GNU C Compiler that instruments all memory references, is available  on
       Linux systems and where GCC is used. It performs	some of	the same tasks
       as Purify, but only on code that	it has compiled.

				 27-April-1993			     efence(3)

NAME | SYNOPSIS | DESCRIPTION | USAGE | GLOBAL AND ENVIRONMENT VARIABLES | WORD-ALIGNMENT AND OVERRUN DETECTION | INSTRUCTIONS FOR DEBUGGING YOUR PROGRAM | MEMORY USAGE AND EXECUTION SPEED | MAILING LIST | AUTHOR | WARNINGS | LICENSE | CONTACTING THE AUTHOR | FILES | SEE ALSO | DIAGNOSTICS | BUGS | WHAT'S BETTER

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=efence&manpath=Red+Hat+Linux%2fi386+7.1>

home | help