efence - Electric Fence Malloc Debugger
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;
Electric Fence helps you detect two common programming bugs: software that overruns 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 pinpoint the exact instruction that
causes an error. It has been in use at Pixar since 1987, and at many other sites for
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, stopping 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 seg-
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.
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 command 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 exe-
cutables. The command 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 create huge core files, and some operat-
ing 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 state-
ment, and repair it.
GLOBAL AND ENVIRONMENT VARIABLES
Electric Fence has four configuration switches that can be enabled via the shell environ-
ment, or by setting the value of global integer variables using a debugger. These switches
change what bugs Electric Fence will detect, so it's important that you know how to use
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 alloca-
tion that is returned by Electric Fence malloc() is aligned using the value in
EF_ALIGNMENT, and its size the multiple 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.
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_PROTECT_BELOW to 1 causes Electric Fence to place the inacces-
sible page before the allocation in the address space, so that under-runs will be
detected instead of over-runs. When EF_PROTECT_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.
Electric Fence usually returns free memory to a pool from which it may be re-allo-
cated. If you suspect that a program may be touching free memory, set EF_PRO-
TECT_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 parameter 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.
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.
When set to a value between 0 and 255, every byte of allocated memory is initial-
ized 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 sys-
tems) 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 virtual memory pages for each allocation. The last page is
made inaccessible in such a way that any read, write, or execute access will cause a seg-
mentation 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. Unfortunately, malloc() is required to return
word-aligned allocations, since many CPUs can only access a word when its address is
aligned. The conflict 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 val-
loc() 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 realloc(). To debug overruns as small as a sin-
gle 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 segmentation 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 probably 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 references instead of word ref-
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 OVERRUN 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 manipulate 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.
There is a mailing list to support Electric Fence. You can subscribe using the mail form
at http://lists.perens.com/mailman/listinfo/electric-fence .
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 software has no warranty. It will not
detect some bugs that you might expect it to detect, and will indicate that some non-bugs
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 published by the Free Software Foundation. A
copy of this license is distributed 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 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
Read the file "COPYING" for more details.
CONTACTING THE AUTHOR
1563 Solano Ave. #349
Berkeley, CA 94707
/dev/zero: Source of memory pages (via mmap(2)).
malloc(3), mmap(2), mprotect(2), swapon(8)
Segmentation Fault: Examine the offending statement for violation of the boundaries of a
Bus Error: See the section on WORD-ALIGNMENT AND OVERRUN DETECTION. in this manual page.
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
There are, without doubt, other bugs and porting issues. Please contact me via e-mail if
you have any bug reports, ideas, etc.
Purify does a much more thorough job than Electric Fence, and does not have the huge mem-
ory 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.