1efence(3) Library Functions Manual efence(3)
2
6 efence - Electric Fence Malloc Debugger
7
9 #include <stdlib.h>
10 void * malloc (size_t size);
12 void free (void *ptr);
14 void * realloc (void *ptr, size_t size);
16 void * calloc (size_t nelem, size_t elsize);
18 void * memalign (size_t alignment, size_t size);
20 void * valloc (size_t size);
22 extern int EF_ALIGNMENT;
24 extern int EF_PROTECT_BELOW;
26 extern int EF_PROTECT_FREE;
28 extern int EF_ALLOW_MALLOC_0;
30 extern int EF_FILL;
32
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 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 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
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 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 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
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 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 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 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 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 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
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 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 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 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
206 1. Link with libefence.a as explained above.
207 2. Run your program in a debugger and fix any overruns or accesses
209 to free memory.
210 3. Quit the debugger.
212 4. Set EF_PROTECT_BELOW = 1 in the shell environment.
214 5. Repeat step 2, this time repairing underruns if they occur.
216 6. Quit the debugger.
218 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
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 Don't leave libefence.a linked into production software! Use it only
236 for debugging.
237
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
244 Bruce Perens
245
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
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 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
265 Bruce Perens
266 1563 Solano Ave. #349
267 Berkeley, CA 94707
268 Telephone: 510-526-1165
269 Internet: bruce@perens.com
270
272 /dev/zero: Source of memory pages (via mmap(2)).
273
275 malloc(3), mmap(2), mprotect(2), swapon(8)
276
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
284 My explanation of the alignment issue could be improved.
285 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 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
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 27-April-1993 efence(3)