Annotation of embedaddon/ntp/ElectricFence/libefence.3, revision 1.1.1.1
1.1 misho 1: .TH efence 3 27-April-1993
2: .SH NAME
3: efence \- Electric Fence Malloc Debugger
4: .SH SYNOPSIS
5: .nf
6: .ft B
7: #include <stdlib.h>
8: .ft
9: .fi
10: .LP
11: .nf
12: .ft B
13: void * malloc (size_t size);
14: .ft
15: .fi
16: .LP
17: .nf
18: .ft B
19: void free (void *ptr);
20: .ft
21: .fi
22: .LP
23: .nf
24: .ft B
25: void * realloc (void *ptr, size_t size);
26: .ft
27: .fi
28: .LP
29: .nf
30: .ft B
31: void * calloc (size_t nelem, size_t elsize);
32: .ft
33: .fi
34: .LP
35: .nf
36: .ft B
37: void * memalign (size_t alignment, size_t size);
38: .ft
39: .fi
40: .LP
41: .nf
42: .ft B
43: void * valloc (size_t size);
44: .ft
45: .fi
46: .LP
47: .nf
48: .ft B
49: extern int EF_ALIGNMENT;
50: .ft
51: .fi
52: .LP
53: .nf
54: .ft B
55: extern int EF_PROTECT_BELOW;
56: .ft
57: .fi
58: .LP
59: .nf
60: .ft B
61: extern int EF_PROTECT_FREE;
62: .ft
63: .fi
64: .SH DESCRIPTION
65: .I Electric Fence
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
70: detect
71: .I read
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
74: sites for years.
75: .LP
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,
79: the
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
84: segmentation fault.
85: .LP
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
89: .I all
90: bugs of this type, you'll have to read and understand the rest of this
91: man page.
92: .SH USAGE
93: Link your program with the library
94: .B libefence.a .
95: Make sure you are
96: .I not
97: linking with
98: .B -lmalloc,
99: .B -lmallocdebug,
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
104: .B -lefence
105: argument to the linker, otherwise you'll have to put the path-name for
106: .B libefence.a
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
111: .br
112: .B -bnso
113: .B -bnodelcsect
114: .B -bI:/lib/syscalls.exp
115: .br
116: On Sun systems running SunOS 4.X, you'll probably have to use
117: .B -Bstatic.
118: .LP
119: Run your program
120: .I using a debugger.
121: It's easier to work this way than to create a
122: .B core
123: file and post-mortem debug it. Electric Fence can create
124: .I huge
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.
136: .TP
137: EF_ALIGNMENT
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
146: .B int
147: you'll have to set this value to 8. This is the case when compiling with the
148: .B -mips2
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
153: .I that value
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
156: alignment), so that
157: you can detect overruns of less than your CPU's word size. Be sure to read
158: the section
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.
164: .TP
165: EF_PROTECT_BELOW
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
170: .I before
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
178: a debugger.
179: .TP
180: EF_PROTECT_FREE
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
186: parameter is set.
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
189: a debugger.
190: .TP
191: EF_ALLOW_MALLOC_0
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
197: a debugger.
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
205: byte after
206: the end of the allocation is on the inaccessible page.
207: Thus, any overrun
208: of the allocation will cause a segmentation fault.
209: .LP
210: It follows that the
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
214: .I word-aligned
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
221: word size.
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.
228: .LP
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.
244: .LP
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
252: of word references.
253: .SH INSTRUCTIONS FOR DEBUGGING YOUR PROGRAM
254: .TP
255: 1.
256: Link with libefence.a as explained above.
257: .TP
258: 2.
259: Run your program in a debugger and fix any overruns or accesses to free memory.
260: .TP
261: 3.
262: Quit the debugger.
263: .TP
264: 4.
265: Set EF_PROTECT_BELOW = 1 in the shell environment.
266: .TP
267: 5.
268: Repeat step 2, this time repairing underruns if they occur.
269: .TP
270: 6.
271: Quit the debugger.
272: .TP
273: 7.
274: Read the restrictions in the section on
275: .I WORD-ALIGNMENT AND OVERRUN DETECTION.
276: See if you can
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.
288: .LP
289: Don't leave libefence.a linked into production software! Use it only
290: for debugging.
291: .SH PORTING
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:
297: .IP
298: A way to allocate memory pages
299: .br
300: A way to make selected pages inaccessible.
301: .br
302: A way to make the pages accessible again.
303: .br
304: A way to detect when a program touches an inaccessible page.
305: .br
306: A way to print messages.
307: .LP
308: Please e-mail me a copy of any changes you have to make, so that I can
309: merge them into the distribution.
310: .SH AUTHOR
311: Bruce Perens
312: .SH WARNINGS
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.
325: .SH LICENSE
326: Copyright 1987-1995 Bruce Perens. All rights reserved.
327: .br
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".
332:
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
338: .nf
339: Bruce Perens
340: c/o Pixar
341: 1001 West Cutting Blvd., Suite 200
342: Richmond, CA 94804
343:
344: Telephone: 510-215-3502
345: Fax: 510-236-0388
346: Internet: Bruce@Pixar.com
347: .fi
348: .ft
349: .SH FILES
350: /dev/zero: Source of memory pages (via mmap(2)).
351: .SH SEE ALSO
352: malloc(3), mmap(2), mprotect(2), swapon(8)
353: .SH DIAGNOSTICS
354: Segmentation Fault: Examine the offending statement for violation of the
355: boundaries of a memory allocation.
356: .br
357: Bus Error: See the section on
358: .I WORD-ALIGNMENT AND OVERRUN DETECTION.
359: in this manual page.
360: .SH BUGS
361: My explanation of the alignment issue could be improved.
362: .LP
363: Some Sun systems running SunOS 4.1 are reported to signal an access to a
364: protected page with
365: .B SIGBUS
366: rather than
367: .B SIGSEGV,
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
371: Makefile to define
372: .B PAGE_PROTECTION_VIOLATED_SIGNAL
373: as
374: .B SIGBUS.
375: .LP
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.
378: .SH WHAT'S BETTER
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.
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>
![[BACK]](/icons/cvsweb/back.gif){kind=icon}
Return to libefence.3 CVS log ![[TXT]](/icons/cvsweb/text.gif){kind=icon}
![[DIR]](/icons/cvsweb/dir.gif){kind=icon}
Up to [ELWIX - Embedded LightWeight unIX -] / embedaddon / ntp / ElectricFence