Annotation of embedaddon/ntp/ElectricFence/libefence.3, revision 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