Provided by: electric-fence_2.2.6_amd64 
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);
int posix_memalign (void ** memptr, size_t alignment, size_t size);
void * valloc (size_t size);
extern int EF_DISABLE_BANNER;
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 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 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, 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 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 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 executables.
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 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 program 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 six configuration switches that can be enabled via the shell environment, 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 them.
EF_DISABLE_BANNER
This is an integer which if nonzero specifies that the usual Electric Fence banner and copyright
notice should not be printed. This is provided for certain circumstances where the banner can be
annoying (eg, running a regression test suite that also monitors stderr). Note that you should
almost certainly not set this in your program, because then you might leave Electric Fence linked
into the production version, which would be very bad.
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 multiple
of that value that is greater than or equal to the requested size. For this reason, you will
sometimes want to set EF_ALIGNMENT 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_PROTECT_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_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.
EF_PROTECT_FREE
When EF_PROTECT_FREE is not set (i. e. set to 0), Electric Fence returns free memory to a pool and
only checks accesses to it until it is reallocated. 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 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.
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_ALLOW_MALLOC_0 in the shell
environment to an integer value, or assign to the global integer variable EF_ALLOW_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
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 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. 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 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 realloc(). 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 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 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 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.
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 software 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 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
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)