1efence(3)                  Library Functions Manual                  efence(3)
2
3
4

NAME

6       efence - Electric Fence Malloc Debugger
7

SYNOPSIS

9       #include <stdlib.h>
10
11       void * malloc (size_t size);
12
13       void free (void *ptr);
14
15       void * realloc (void *ptr, size_t size);
16
17       void * calloc (size_t nelem, size_t elsize);
18
19       void * memalign (size_t alignment, size_t size);
20
21       void * valloc (size_t size);
22
23       extern int EF_ALIGNMENT;
24
25       extern int EF_PROTECT_BELOW;
26
27       extern int EF_PROTECT_FREE;
28
29       extern int EF_ALLOW_MALLOC_0;
30
31       extern int EF_FILL;
32

DESCRIPTION

34       Electric  Fence  helps you detect two common programming bugs: software
35       that overruns the boundaries of a malloc() memory allocation, and soft‐
36       ware that touches a memory allocation that has been released by free().
37       Unlike other  malloc()  debuggers,  Electric  Fence  will  detect  read
38       accesses  as well as writes, and it will pinpoint the exact instruction
39       that causes an error. It has been in use at Pixar since  1987,  and  at
40       many other sites for years.
41
42       Electric  Fence  uses  the  virtual memory hardware of your computer to
43       place an inaccessible memory page immediately after (or before, at  the
44       user's  option)  each  memory allocation. When software reads or writes
45       this inaccessible page, the hardware issues a segmentation fault, stop‐
46       ping  the  program  at the offending instruction. It is then trivial to
47       find the erroneous statement using your favorite debugger. In a similar
48       manner,  memory  that has been released by free() is made inaccessible,
49       and any code that touches it will get a segmentation fault.
50
51       Simply linking your application with  libefence.a  will  allow  you  to
52       detect  most,  but not all, malloc buffer overruns and accesses of free
53       memory.  If you want to be reasonably sure that you've found  all  bugs
54       of  this  type, you'll have to read and understand the rest of this man
55       page.
56

USAGE

58       Link your program with the library libefence.a .  Make sure you are not
59       linking  with -lmalloc, -lmallocdebug, or with other malloc-debugger or
60       malloc-enhancer libraries.  You can only use one at a  time.   If  your
61       system  administrator  has  installed  Electric  Fence  for public use,
62       you'll be able to use the -lefence argument to  the  linker,  otherwise
63       you'll  have  to put the path-name for libefence.a in the linker's com‐
64       mand line.  You can also use dynamic linking. If you're using a  Bourne
65       shell,  the  statement  export  LD_PRELOAD=libefence.so.0.0  will cause
66       Electric Fence to be loaded to run all dynamic executables.   The  com‐
67       mand ef command runs a single command under Electric Fence.
68
69       Some  systems  will  require  special arguments to the linker to assure
70       that you are using the Electric Fence malloc() and  not  the  one  from
71       your C library.
72
73       Run  your  program using a debugger.  It's easier to work this way than
74       to create a core file and post-mortem debug it. Electric Fence can cre‐
75       ate  huge core files, and some operating systems will thus take minutes
76       simply to dump core! Some operating systems will not create usable core
77       files  from programs that are linked with Electric Fence.  If your pro‐
78       gram has one of the errors detected by Electric Fence, it  will  get  a
79       segmentation  fault  (SIGSEGV)  at  the  offending instruction. Use the
80       debugger to locate the erroneous statement, and repair it.
81

GLOBAL AND ENVIRONMENT VARIABLES

83       Electric Fence has four configuration switches that can be enabled  via
84       the  shell environment, or by setting the value of global integer vari‐
85       ables using a debugger. These switches change what bugs Electric  Fence
86       will detect, so it's important that you know how to use them.
87
88       EF_ALIGNMENT
89              This  is  an integer that specifies the alignment for any memory
90              allocations that will be returned  by  malloc(),  calloc(),  and
91              realloc().   The  value is specified in bytes, thus a value of 4
92              will cause memory to be aligned to 32-bit boundaries unless your
93              system  doesn't  have a 8-bit characters. EF_ALIGNMENT is set to
94              sizeof(int) by default, since that is generally the word-size of
95              your  CPU.  If your program requires that allocations be aligned
96              to 64-bit boundaries and you have a 32-bit int  you'll  have  to
97              set  this  value  to 8. This is the case when compiling with the
98              -mips2 flag on MIPS-based systems such as those from  SGI.   The
99              memory allocation that is returned by Electric Fence malloc() is
100              aligned using the value in EF_ALIGNMENT, and its size the multi‐
101              ple of that value that is greater than or equal to the requested
102              size.  For this reason, you will sometimes want to set EF_ALIGN‐
103              MENT  to  0  (no  alignment), so that you can detect overruns of
104              less than your CPU's word size. Be  sure  to  read  the  section
105              WORD-ALIGNMENT  AND OVERRUN DETECTION in this manual page before
106              you try this.  To change this value,  set  EF_ALIGNMENT  in  the
107              shell  environment  to an integer value, or assign to the global
108              integer variable EF_ALIGNMENT using a debugger.
109
110       EF_PROTECT_BELOW
111              Electric Fence usually places an inaccessible  page  immediately
112              after  each  memory  allocation, so that software that runs past
113              the end of the allocation  will  be  detected.  Setting  EF_PRO‐
114              TECT_BELOW  to 1 causes Electric Fence to place the inaccessible
115              page before the allocation in the address space, so that  under-
116              runs  will  be  detected  instead  of  over-runs.   When EF_PRO‐
117              TECT_BELOW is set, the EF_ALIGNMENT parameter is  ignored.   All
118              allocations  will  be aligned to virtual-memory-page boundaries,
119              and their size will be the exact size that  was  requested.   To
120              change this value, set EF_PROTECT_BELOW in the shell environment
121              to an integer value, or assign to the  global  integer  variable
122              EF_PROTECT_BELOW using a debugger.
123
124       EF_PROTECT_FREE
125              Electric  Fence usually returns free memory to a pool from which
126              it may be re-allocated. If you suspect that  a  program  may  be
127              touching  free memory, set EF_PROTECT_FREE to 1. This will cause
128              Electric Fence to never re-allocate  memory  once  it  has  been
129              freed,  so that any access to free memory will be detected. Some
130              programs will use tremendous amounts of memory when this parame‐
131              ter  is  set.   To change this value, set EF_PROTECT_FREE in the
132              shell environment to an integer value, or assign to  the  global
133              integer variable EF_PROTECT_FREE using a debugger.
134
135       EF_ALLOW_MALLOC_0
136              By  default,  Electric Fence traps calls to malloc() with a size
137              of zero, because they are often the result of a software bug. If
138              EF_ALLOW_MALLOC_0  is non-zero, the software will not trap calls
139              to malloc() with a size of zero.   To  change  this  value,  set
140              EF_ALLOC_MALLOC_0  in the shell environment to an integer value,
141              or assign to the global integer variable EF_ALLOC_MALLOC_0 using
142              a debugger.
143
144       EF_FILL
145              When  set  to a value between 0 and 255, every byte of allocated
146              memory is initialized to that value. This can help detect  reads
147              of  uninitialized memory.  When set to -1, some memory is filled
148              with zeroes (the operating system default on most  systems)  and
149              some memory will retain the values written to it during its last
150              use.
151

WORD-ALIGNMENT AND OVERRUN DETECTION

153       There is a conflict between the alignment  restrictions  that  malloc()
154       operates  under and the debugging strategy used by Electric Fence. When
155       detecting overruns, Electric Fence malloc() allocates two or more  vir‐
156       tual memory pages for each allocation. The last page is made inaccessi‐
157       ble in such a way that any read, write, or execute access will cause  a
158       segmentation  fault.   Then,  Electric  Fence  malloc()  will return an
159       address such that the first byte after the end of the allocation is  on
160       the  inaccessible page.  Thus, any overrun of the allocation will cause
161       a segmentation fault.
162
163       It follows that the address returned by malloc() is the address of  the
164       inaccessible  page  minus  the size of the memory allocation.  Unfortu‐
165       nately, malloc() is required to return word-aligned allocations,  since
166       many CPUs can only access a word when its address is aligned.  The con‐
167       flict happens when software makes a memory allocation using a size that
168       is  not a multiple of the word size, and expects to do word accesses to
169       that allocation. The location of the  inaccessible  page  is  fixed  by
170       hardware  at  a  word-aligned address. If Electric Fence malloc() is to
171       return an aligned address, it must increase the size of the  allocation
172       to  a multiple of the word size.  In addition, the functions memalign()
173       and valloc() must honor explicit specifications on the alignment of the
174       memory  allocation,  and  this,  as  well  can  only  be implemented by
175       increasing the size of the allocation.  Thus, there will be  situations
176       in  which  the  end of a memory allocation contains some padding space,
177       and accesses of that padding space will not be detected, even  if  they
178       are overruns.
179
180       Electric  Fence provides the variable EF_ALIGNMENT so that the user can
181       control the default alignment used by  malloc(),  calloc(),  and  real‐
182       loc().   To  debug  overruns  as  small  as  a single byte, you can set
183       EF_ALIGNMENT to zero. This  will  result  in  Electric  Fence  malloc()
184       returning unaligned addresses for allocations with sizes that are not a
185       multiple of the word size. This is not a problem in most cases, because
186       compilers  must  pad the size of objects so that alignment restrictions
187       are honored when storing those objects in arrays. The problem  surfaces
188       when  software  allocates  odd-sized  buffers  for objects that must be
189       word-aligned. One case of this is software that allocates a  buffer  to
190       contain  a structure and a string, and the string has an odd size (this
191       example was in a popular TIFF library). If word references are made  to
192       un-aligned buffers, you will see a bus error (SIGBUS) instead of a seg‐
193       mentation fault. The only way to fix this is to re-write the  offending
194       code  to  make byte references or not make odd-sized allocations, or to
195       set EF_ALIGNMENT to the word size.
196
197       Another example of software incompatible with EF_ALIGNMENT <  word-size
198       is the strcmp() function and other string functions on SunOS (and prob‐
199       ably Solaris), which make word-sized accesses to character strings, and
200       may  attempt  to  access  up to three bytes beyond the end of a string.
201       These result in a segmentation fault (SIGSEGV).  The  only  way  around
202       this  is to use versions of the string functions that perform byte ref‐
203       erences instead of word references.
204

INSTRUCTIONS FOR DEBUGGING YOUR PROGRAM

206       1.     Link with libefence.a as explained above.
207
208       2.     Run your program in a debugger and fix any overruns or  accesses
209              to free memory.
210
211       3.     Quit the debugger.
212
213       4.     Set EF_PROTECT_BELOW = 1 in the shell environment.
214
215       5.     Repeat step 2, this time repairing underruns if they occur.
216
217       6.     Quit the debugger.
218
219       7.     Read the restrictions in the section on WORD-ALIGNMENT AND OVER‐
220              RUN DETECTION.  See if you can set EF_ALIGNMENT to 0 and  repeat
221              step  2.  Sometimes this will be too much work, or there will be
222              problems with library routines for  which  you  don't  have  the
223              source, that will prevent you from doing this.
224

MEMORY USAGE AND EXECUTION SPEED

226       Since Electric Fence uses at least two virtual memory pages for each of
227       its allocations, it's a terrible memory hog. I've  sometimes  found  it
228       necessary  to  add a swap file using swapon(8) so that the system would
229       have enough virtual memory to debug my program. Also, the way we manip‐
230       ulate  memory  results  in various cache and translation buffer entries
231       being flushed with each call to malloc or free. The end result is  that
232       your  program  will be much slower and use more resources while you are
233       debugging it with Electric Fence.
234
235       Don't leave libefence.a linked into production software!  Use  it  only
236       for debugging.
237

MAILING LIST

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

AUTHOR

244       Bruce Perens
245

WARNINGS

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

LICENSE

253       Copyright 1987-1999 Bruce Perens. All rights reserved.
254       This program is free software; you can redistribute it and/or modify it
255       under  the  terms of the GNU General Public License, Version 2, as pub‐
256       lished by the Free Software Foundation. A copy of this license is  dis‐
257       tributed with this software in the file "COPYING".
258
259       This  program  is  distributed  in the hope that it will be useful, but
260       WITHOUT ANY  WARRANTY;  without  even  the  implied  warranty  of  MER‐
261       CHANTABILITY  or FITNESS FOR A PARTICULAR PURPOSE. Read the file "COPY‐
262       ING" for more details.
263

CONTACTING THE AUTHOR

265       Bruce Perens
266       1563 Solano Ave. #349
267       Berkeley, CA 94707
268       Telephone: 510-526-1165
269       Internet: bruce@perens.com
270

FILES

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

SEE ALSO

275       malloc(3), mmap(2), mprotect(2), swapon(8)
276

DIAGNOSTICS

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

BUGS

284       My explanation of the alignment issue could be improved.
285
286       Some Sun systems running SunOS 4.1 were reported to signal an access to
287       a  protected page with SIGBUS rather than SIGSEGV, I suspect this is an
288       undocumented feature of a particular Sun hardware version, not just the
289       operating  system.  On these systems, eftest will fail with a bus error
290       until you modify the Makefile to define PAGE_PROTECTION_VIOLATED_SIGNAL
291       as SIGBUS.
292
293       There are, without doubt, other bugs and porting issues. Please contact
294       me via e-mail if you have any bug reports, ideas, etc.
295

WHAT'S BETTER

297       Purify does a much more thorough job than Electric Fence, and does  not
298       have  the  huge memory overhead.  Checkergcc, a modified version of the
299       GNU C Compiler that instruments all memory references, is available  on
300       Linux systems and where GCC is used. It performs some of the same tasks
301       as Purify, but only on code that it has compiled.
302
303
304
305                                 27-April-1993                       efence(3)
Impressum