1 .TH efence 3 27-April-1993
3 efence \- Electric Fence Malloc Debugger
13 void * malloc (size_t size);
19 void free (void *ptr);
25 void * realloc (void *ptr, size_t size);
31 void * calloc (size_t nelem, size_t elsize);
37 void * memalign (size_t alignment, size_t size);
43 void * valloc (size_t size);
49 extern int EF_ALIGNMENT;
55 extern int EF_PROTECT_BELOW;
61 extern int EF_PROTECT_FREE;
66 helps you detect two common programming bugs:
67 software that overruns the boundaries of a malloc() memory
68 allocation, and software that touches a memory allocation that has been
69 released by free(). Unlike other malloc() debuggers, Electric Fence will
72 accesses as well as writes, and it will pinpoint the exact instruction that
73 causes an error. It has been in use at Pixar since 1987, and at many other
76 Electric Fence uses the virtual memory hardware of your computer to place an
77 inaccessible memory page immediately after (or before, at the user's option)
78 each memory allocation. When software reads or writes this inaccessible page,
80 hardware issues a segmentation fault, stopping the program at the offending
81 instruction. It is then trivial to find the erroneous statement using your
82 favorite debugger. In a similar manner, memory that has been released by
83 free() is made inaccessible, and any code that touches it will get a
86 Simply linking your application with libefence.a will allow you to detect
87 most, but not all, malloc buffer overruns and accesses of free memory.
88 If you want to be reasonably sure that you've found
90 bugs of this type, you'll have to read and understand the rest of this
93 Link your program with the library
100 or with other malloc-debugger or malloc-enhancer libraries.
101 You can only use one at a time.
102 If your system administrator
103 has installed Electric Fence for public use, you'll be able to use the
105 argument to the linker, otherwise you'll have to put the path-name for
107 in the linker's command line.
108 Some systems will require special arguments to the linker to assure that
109 you are using the Electric Fence malloc() and not the one from your C library.
110 On AIX systems, you may have to use the flags
114 .B -bI:/lib/syscalls.exp
116 On Sun systems running SunOS 4.X, you'll probably have to use
121 It's easier to work this way than to create a
123 file and post-mortem debug it. Electric Fence can create
125 core files, and some operating systems will thus take minutes simply to dump
126 core! Some operating systems will not create usable core files from programs
127 that are linked with Electric Fence.
128 If your program has one of the errors detected by Electric Fence, it will
129 get a segmentation fault (SIGSEGV) at the offending instruction. Use the
130 debugger to locate the erroneous statement, and repair it.
131 .SH GLOBAL AND ENVIRONMENT VARIABLES
132 Electric Fence has four configuration switches that can be enabled via
133 the shell environment, or by setting the value of global integer variables
134 using a debugger. These switches change what bugs Electric Fence will detect,
135 so it's important that you know how to use them.
138 This is an integer that specifies the alignment for any memory allocations
139 that will be returned by malloc(), calloc(), and realloc().
140 The value is specified in
141 bytes, thus a value of 4 will cause memory to be aligned to 32-bit boundaries
142 unless your system doesn't have a 8-bit characters. EF_ALIGNMENT is set to
143 sizeof(int) by default, since that is generally the word-size of your CPU.
144 If your program requires that allocations be aligned to 64-bit
145 boundaries and you have a 32-bit
147 you'll have to set this value to 8. This is the case when compiling with the
149 flag on MIPS-based systems such as those from SGI.
150 The memory allocation that is returned by Electric Fence malloc() is aligned
151 using the value in EF_ALIGNMENT, and
152 .I its size the multiple of
154 that is greater than or equal to the requested size.
155 For this reason, you will sometimes want to set EF_ALIGNMENT to 0 (no
157 you can detect overruns of less than your CPU's word size. Be sure to read
159 .I WORD-ALIGNMENT AND OVERRUN DETECTION
160 in this manual page before you try this.
161 To change this value, set EF_ALIGNMENT in the shell environment to an
162 integer value, or assign
163 to the global integer variable EF_ALIGNMENT using a debugger.
166 Electric Fence usually places an inaccessible page immediately after each
167 memory allocation, so that software that runs past the end of the allocation
168 will be detected. Setting EF_PROTECT_BELOW to 1 causes Electric Fence
169 to place the inaccessible page
171 the allocation in the address space, so that under-runs will be detected
172 instead of over-runs.
173 When EF_PROTECT_BELOW is set, the EF_ALIGNMENT parameter is ignored.
174 All allocations will be aligned to virtual-memory-page boundaries, and
175 their size will be the exact size that was requested.
176 To change this value, set EF_PROTECT_BELOW in the shell environment to an
177 integer value, or assign to the global integer variable EF_PROTECT_BELOW using
181 Electric Fence usually returns free memory to a pool from which it may be
182 re-allocated. If you suspect that a program may be touching free memory,
183 set EF_PROTECT_FREE to 1. This will cause Electric Fence to never re-allocate
184 memory once it has been freed, so that any access to free memory will be
185 detected. Some programs will use tremendous amounts of memory when this
187 To change this value, set EF_PROTECT_FREE in the shell environment to an
188 integer value, or assign to the global integer variable EF_PROTECT_FREE using
192 By default, Electric Fence traps calls to malloc() with a size of zero, because
193 they are often the result of a software bug. If EF_ALLOW_MALLOC_0 is non-zero,
194 the software will not trap calls to malloc() with a size of zero.
195 To change this value, set EF_ALLOC_MALLOC_0 in the shell environment to an
196 integer value, or assign to the global integer variable EF_ALLOC_MALLOC_0 using
198 .SH WORD-ALIGNMENT AND OVERRUN DETECTION
199 There is a conflict between the alignment restrictions that malloc() operates
200 under and the debugging strategy used by Electric Fence. When detecting
201 overruns, Electric Fence malloc() allocates two or more virtual memory
202 pages for each allocation. The last page is made inaccessible in such a way
203 that any read, write, or execute access will cause a segmentation fault.
204 Then, Electric Fence malloc() will return an address such that the first
206 the end of the allocation is on the inaccessible page.
208 of the allocation will cause a segmentation fault.
211 address returned by malloc() is the address of the inaccessible page minus
212 the size of the memory allocation.
213 Unfortunately, malloc() is required to return
215 allocations, since many CPUs can only access a word when its address is aligned.
216 The conflict happens when software makes a memory allocation using a size that
217 is not a multiple of the word size, and expects to do word accesses to that
218 allocation. The location of the inaccessible page is fixed by hardware at
219 a word-aligned address. If Electric Fence malloc() is to return an aligned
220 address, it must increase the size of the allocation to a multiple of the
222 In addition, the functions memalign() and valloc() must honor explicit
223 specifications on the alignment of the memory allocation, and this, as well
224 can only be implemented by increasing the size of the allocation.
225 Thus, there will be situations in which the end of a memory allocation
226 contains some padding space, and accesses of that padding space will not
227 be detected, even if they are overruns.
229 Electric Fence provides the variable EF_ALIGNMENT so that the user can
230 control the default alignment used by malloc(), calloc(), and realloc().
231 To debug overruns as small as a single byte, you can set EF_ALIGNMENT to
232 zero. This will result in Electric Fence malloc() returning unaligned
233 addresses for allocations with sizes that are not a multiple of the word
234 size. This is not a problem in most cases, because compilers must pad the
235 size of objects so that alignment restrictions are honored when storing
236 those objects in arrays. The problem surfaces when software allocates
237 odd-sized buffers for objects that must be word-aligned. One case of this
238 is software that allocates a buffer to contain a structure and a
239 string, and the string has an odd size (this example was in a popular TIFF
240 library). If word references are made to un-aligned buffers, you will see
241 a bus error (SIGBUS) instead of a segmentation fault. The only way to fix
242 this is to re-write the offending code to make byte references or not make
243 odd-sized allocations, or to set EF_ALIGNMENT to the word size.
245 Another example of software incompatible with
246 EF_ALIGNMENT < word-size
247 is the strcmp() function and other string functions on SunOS (and probably
248 Solaris), which make word-sized accesses to character strings, and may
249 attempt to access up to three bytes beyond the end of a string. These
250 result in a segmentation fault (SIGSEGV). The only way around this is to
251 use versions of the string functions that perform byte references instead
253 .SH INSTRUCTIONS FOR DEBUGGING YOUR PROGRAM
256 Link with libefence.a as explained above.
259 Run your program in a debugger and fix any overruns or accesses to free memory.
265 Set EF_PROTECT_BELOW = 1 in the shell environment.
268 Repeat step 2, this time repairing underruns if they occur.
274 Read the restrictions in the section on
275 .I WORD-ALIGNMENT AND OVERRUN DETECTION.
277 set EF_ALIGNMENT to 0 and repeat step 2. Sometimes this will be too much work,
278 or there will be problems with library routines for which you don't have the
279 source, that will prevent you from doing this.
280 .SH MEMORY USAGE AND EXECUTION SPEED
281 Since Electric Fence uses at least two virtual memory pages for each of its
282 allocations, it's a terrible memory hog. I've sometimes found it necessary to
283 add a swap file using swapon(8) so that the system would have enough virtual
284 memory to debug my program. Also, the way we manipulate memory results in
285 various cache and translation buffer entries being flushed with each call
286 to malloc or free. The end result is that your program will be much slower
287 and use more resources while you are debugging it with Electric Fence.
289 Don't leave libefence.a linked into production software! Use it only
292 Electric Fence is written for ANSI C. You should be able to port it with
293 simple changes to the Makefile and to page.c,
294 which contains the memory management primitives .
295 Many POSIX platforms will require only a re-compile.
296 The operating system facilities required to port Electric Fence are:
298 A way to allocate memory pages
300 A way to make selected pages inaccessible.
302 A way to make the pages accessible again.
304 A way to detect when a program touches an inaccessible page.
306 A way to print messages.
308 Please e-mail me a copy of any changes you have to make, so that I can
309 merge them into the distribution.
313 I have tried to do as good a job as I can on this software, but I doubt
314 that it is even theoretically possible to make it bug-free.
315 This software has no warranty. It will not detect some bugs that you might
316 expect it to detect, and will indicate that some non-bugs are bugs.
317 Bruce Perens and/or Pixar will not be liable to any claims resulting
318 from the use of this software or the ideas within it.
319 The entire responsibility for its use must
320 be assumed by the user. If you use it and it results in loss of life
321 and/or property, tough. If it leads you on a wild goose chase and you waste
322 two weeks debugging something, too bad.
323 If you can't deal with the above, please don't use the software! I've written
324 this in an attempt to help other people, not to get myself sued or prosecuted.
326 Copyright 1987-1995 Bruce Perens. All rights reserved.
328 This program is free software; you can redistribute it and/or modify
329 it under the terms of the GNU General Public License, Version 2,
330 as published by the Free Software Foundation. A copy of this license is
331 distributed with this software in the file "COPYING".
333 This program is distributed in the hope that it will be useful,
334 but WITHOUT ANY WARRANTY; without even the implied warranty of
335 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. Read the
336 file "COPYING" for more details.
337 .SH CONTACTING THE AUTHOR
341 1001 West Cutting Blvd., Suite 200
344 Telephone: 510-215-3502
346 Internet: Bruce@Pixar.com
350 /dev/zero: Source of memory pages (via mmap(2)).
352 malloc(3), mmap(2), mprotect(2), swapon(8)
354 Segmentation Fault: Examine the offending statement for violation of the
355 boundaries of a memory allocation.
357 Bus Error: See the section on
358 .I WORD-ALIGNMENT AND OVERRUN DETECTION.
361 My explanation of the alignment issue could be improved.
363 Some Sun systems running SunOS 4.1 are reported to signal an access to a
368 I suspect this is an undocumented feature of a particular Sun hardware
369 version, not just the operating system.
370 On these systems, eftest will fail with a bus error until you modify the
372 .B PAGE_PROTECTION_VIOLATED_SIGNAL
376 There are, without doubt, other bugs and porting issues. Please contact me via
377 e-mail if you have any bug reports, ideas, etc.
379 PURIFY, from Purify Systems, does a much better job than Electric Fence, and
380 does much more. It's available at this writing on SPARC and HP.
381 I'm not affiliated with Purify, I just think it's a wonderful product
382 and you should check it out.
projects / profile / ivi / ntp.git / blob