Home Man
Search
Today's Posts
Register

Linux & Unix Commands - Search Man Pages

RedHat 9 (Linux i386) - man page for efence (redhat section 3)

efence(3)			     Library Functions Manual				efence(3)

NAME
       efence - Electric Fence Malloc Debugger

SYNOPSIS
       #include <stdlib.h>

       void * malloc (size_t size);

       void free (void *ptr);

       void * realloc (void *ptr, size_t size);

       void * calloc (size_t nelem, size_t elsize);

       void * memalign (size_t alignment, size_t size);

       void * valloc (size_t size);

       extern int EF_ALIGNMENT;

       extern int EF_PROTECT_BELOW;

       extern int EF_PROTECT_FREE;

       extern int EF_ALLOW_MALLOC_0;

       extern int EF_FILL;

DESCRIPTION
       Electric  Fence	helps  you detect two common programming bugs: software that overruns the
       boundaries of a malloc() memory allocation, and software that touches a memory  allocation
       that  has  been	released  by free(). Unlike other malloc() debuggers, Electric Fence will
       detect read accesses as well as writes, and it will pinpoint the  exact	instruction  that
       causes  an  error.  It  has  been  in use at Pixar since 1987, and at many other sites for
       years.

       Electric Fence uses the virtual memory hardware of your computer to place an  inaccessible
       memory  page  immediately  after (or before, at the user's option) each memory allocation.
       When software reads or writes this inaccessible page, the hardware issues  a  segmentation
       fault,  stopping  the program at the offending instruction. It is then trivial to find the
       erroneous statement using your favorite debugger. In a similar  manner,	memory	that  has
       been released by free() is made inaccessible, and any code that touches it will get a seg-
       mentation fault.

       Simply linking your application with libefence.a will allow you to detect  most,  but  not
       all,  malloc  buffer  overruns  and accesses of free memory.  If you want to be reasonably
       sure that you've found all bugs of this type, you'll have to read and understand the  rest
       of this man page.

USAGE
       Link  your  program  with  the  library	libefence.a .  Make sure you are not linking with
       -lmalloc, -lmallocdebug, or with other malloc-debugger or malloc-enhancer libraries.   You
       can only use one at a time.  If your system administrator has installed Electric Fence for
       public use, you'll be able to use the -lefence argument to the  linker,	otherwise  you'll
       have  to put the path-name for libefence.a in the linker's command line.  You can also use
       dynamic	 linking.   If	 you're   using   a   Bourne   shell,	the   statement    export
       LD_PRELOAD=libefence.so.0.0 will cause Electric Fence to be loaded to run all dynamic exe-
       cutables.  The command ef command runs a single command under Electric Fence.

       Some systems will require special arguments to the linker to assure that you are using the
       Electric Fence malloc() and not the one from your C library.

       Run  your  program  using  a debugger.  It's easier to work this way than to create a core
       file and post-mortem debug it. Electric Fence can create huge core files, and some operat-
       ing  systems  will  thus take minutes simply to dump core! Some operating systems will not
       create usable core files from programs that are linked with Electric Fence.  If your  pro-
       gram  has  one  of the errors detected by Electric Fence, it will get a segmentation fault
       (SIGSEGV) at the offending instruction. Use the debugger to locate  the	erroneous  state-
       ment, and repair it.

GLOBAL AND ENVIRONMENT VARIABLES
       Electric  Fence has four configuration switches that can be enabled via the shell environ-
       ment, or by setting the value of global integer variables using a debugger. These switches
       change  what  bugs  Electric Fence will detect, so it's important that you know how to use
       them.

       EF_ALIGNMENT
	      This is an integer that specifies the alignment for  any	memory	allocations  that
	      will  be	returned by malloc(), calloc(), and realloc().	The value is specified in
	      bytes, thus a value of 4 will cause memory  to  be  aligned  to  32-bit  boundaries
	      unless  your  system  doesn't  have  a  8-bit  characters.  EF_ALIGNMENT	is set to
	      sizeof(int) by default, since that is generally the word-size of your CPU.  If your
	      program  requires  that  allocations be aligned to 64-bit boundaries and you have a
	      32-bit int you'll have to set this value to 8. This is the case when compiling with
	      the  -mips2  flag on MIPS-based systems such as those from SGI.  The memory alloca-
	      tion that is returned by Electric Fence malloc() is  aligned  using  the	value  in
	      EF_ALIGNMENT, and its size the multiple of that value that is greater than or equal
	      to the requested size.  For this reason, you will sometimes want to  set	EF_ALIGN-
	      MENT  to	0 (no alignment), so that you can detect overruns of less than your CPU's
	      word size. Be sure to read the section WORD-ALIGNMENT AND OVERRUN DETECTION in this
	      manual  page  before  you  try this.  To change this value, set EF_ALIGNMENT in the
	      shell environment to an integer value, or assign to  the	global	integer  variable
	      EF_ALIGNMENT using a debugger.

       EF_PROTECT_BELOW
	      Electric	Fence  usually	places an inaccessible page immediately after each memory
	      allocation, so that software that runs past the  end  of	the  allocation  will  be
	      detected. Setting EF_PROTECT_BELOW to 1 causes Electric Fence to place the inacces-
	      sible page before the allocation in the address space, so that under-runs  will  be
	      detected	instead  of  over-runs.   When	EF_PROTECT_BELOW is set, the EF_ALIGNMENT
	      parameter is ignored.  All  allocations  will  be  aligned  to  virtual-memory-page
	      boundaries,  and	their  size will be the exact size that was requested.	To change
	      this value, set EF_PROTECT_BELOW in the shell environment to an integer  value,  or
	      assign to the global integer variable EF_PROTECT_BELOW using a debugger.

       EF_PROTECT_FREE
	      Electric	Fence usually returns free memory to a pool from which it may be re-allo-
	      cated. If you suspect that a program may	be  touching  free  memory,  set  EF_PRO-
	      TECT_FREE  to 1. This will cause Electric Fence to never re-allocate memory once it
	      has been freed, so that any access to free memory will be detected.  Some  programs
	      will  use  tremendous amounts of memory when this parameter is set.  To change this
	      value, set EF_PROTECT_FREE in the shell environment to an integer value, or  assign
	      to the global integer variable EF_PROTECT_FREE using a debugger.

       EF_ALLOW_MALLOC_0
	      By  default,  Electric  Fence  traps calls to malloc() with a size of zero, because
	      they are often the result of a software bug. If EF_ALLOW_MALLOC_0 is non-zero,  the
	      software	will  not  trap  calls	to  malloc() with a size of zero.  To change this
	      value, set EF_ALLOC_MALLOC_0 in the shell  environment  to  an  integer  value,  or
	      assign to the global integer variable EF_ALLOC_MALLOC_0 using a debugger.

       EF_FILL
	      When  set  to a value between 0 and 255, every byte of allocated memory is initial-
	      ized to that value. This can help detect reads of uninitialized memory.	When  set
	      to -1, some memory is filled with zeroes (the operating system default on most sys-
	      tems) and some memory will retain the values written to it during its last use.

WORD-ALIGNMENT AND OVERRUN DETECTION
       There is a conflict between the alignment restrictions that malloc()  operates  under  and
       the  debugging  strategy  used  by Electric Fence. When detecting overruns, Electric Fence
       malloc() allocates two or more virtual memory pages for each allocation. The last page  is
       made  inaccessible in such a way that any read, write, or execute access will cause a seg-
       mentation fault.  Then, Electric Fence malloc() will return an address such that the first
       byte  after  the  end of the allocation is on the inaccessible page.  Thus, any overrun of
       the allocation will cause a segmentation fault.

       It follows that the address returned by malloc() is the address of the  inaccessible  page
       minus  the  size  of the memory allocation.  Unfortunately, malloc() is required to return
       word-aligned allocations, since many CPUs can only access  a  word  when  its  address  is
       aligned.   The  conflict happens when software makes a memory allocation using a size that
       is not a multiple of the word size, and expects to do word accesses  to	that  allocation.
       The  location  of the inaccessible page is fixed by hardware at a word-aligned address. If
       Electric Fence malloc() is to return an aligned address, it must increase the size of  the
       allocation to a multiple of the word size.  In addition, the functions memalign() and val-
       loc() must honor explicit specifications on the alignment of the  memory  allocation,  and
       this,  as  well	can  only be implemented by increasing the size of the allocation.  Thus,
       there will be situations in which the end of a memory  allocation  contains  some  padding
       space, and accesses of that padding space will not be detected, even if they are overruns.

       Electric Fence provides the variable EF_ALIGNMENT so that the user can control the default
       alignment used by malloc(), calloc(), and realloc().  To debug overruns as small as a sin-
       gle  byte,  you	can set EF_ALIGNMENT to zero. This will result in Electric Fence malloc()
       returning unaligned addresses for allocations with sizes that are not a	multiple  of  the
       word  size.  This  is  not a problem in most cases, because compilers must pad the size of
       objects so that alignment restrictions are honored when storing those objects  in  arrays.
       The  problem  surfaces  when software allocates odd-sized buffers for objects that must be
       word-aligned. One case of this is software that allocates a buffer to contain a	structure
       and a string, and the string has an odd size (this example was in a popular TIFF library).
       If word references are made to un-aligned buffers, you  will  see  a  bus  error  (SIGBUS)
       instead	of  a  segmentation  fault. The only way to fix this is to re-write the offending
       code to make byte references or not make odd-sized allocations, or to set EF_ALIGNMENT  to
       the word size.

       Another	example  of  software  incompatible with EF_ALIGNMENT < word-size is the strcmp()
       function and other string functions on SunOS (and probably Solaris), which make word-sized
       accesses  to character strings, and may attempt to access up to three bytes beyond the end
       of a string. These result in a segmentation fault (SIGSEGV). The only way around  this  is
       to  use versions of the string functions that perform byte references instead of word ref-
       erences.

INSTRUCTIONS FOR DEBUGGING YOUR PROGRAM
       1.     Link with libefence.a as explained above.

       2.     Run your program in a debugger and fix any overruns or accesses to free memory.

       3.     Quit the debugger.

       4.     Set EF_PROTECT_BELOW = 1 in the shell environment.

       5.     Repeat step 2, this time repairing underruns if they occur.

       6.     Quit the debugger.

       7.     Read the restrictions in the section on WORD-ALIGNMENT AND OVERRUN DETECTION.   See
	      if you can set EF_ALIGNMENT to 0 and repeat step 2. Sometimes this will be too much
	      work, or there will be problems with library routines for which you don't have  the
	      source, that will prevent you from doing this.

MEMORY USAGE AND EXECUTION SPEED
       Since  Electric	Fence uses at least two virtual memory pages for each of its allocations,
       it's a terrible memory hog. I've sometimes found it necessary to add  a	swap  file  using
       swapon(8)  so  that the system would have enough virtual memory to debug my program. Also,
       the way we manipulate memory results in various cache and translation buffer entries being
       flushed with each call to malloc or free. The end result is that your program will be much
       slower and use more resources while you are debugging it with Electric Fence.

       Don't leave libefence.a linked into production software! Use it only for debugging.

MAILING LIST
       There is a mailing list to support Electric Fence. You can subscribe using the  mail  form
       at http://lists.perens.com/mailman/listinfo/electric-fence .

AUTHOR
       Bruce Perens

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

LICENSE
       Copyright 1987-1999 Bruce Perens. All rights reserved.
       This program is free software; you can redistribute it and/or modify it under the terms of
       the GNU General Public License, Version 2, as published by the Free Software Foundation. A
       copy of this license is distributed with this software in the file "COPYING".

       This program is distributed in the hope that it will be useful, but WITHOUT ANY	WARRANTY;
       without	even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
       Read the file "COPYING" for more details.

CONTACTING THE AUTHOR
       Bruce Perens
       1563 Solano Ave. #349
       Berkeley, CA 94707
       Telephone: 510-526-1165
       Internet: bruce@perens.com

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

SEE ALSO
       malloc(3), mmap(2), mprotect(2), swapon(8)

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

BUGS
       My explanation of the alignment issue could be improved.

       Some  Sun  systems running SunOS 4.1 were reported to signal an access to a protected page
       with SIGBUS rather than SIGSEGV, I suspect this is an undocumented feature of a particular
       Sun  hardware  version, not just the operating system.  On these systems, eftest will fail
       with a bus error until you modify the Makefile to  define  PAGE_PROTECTION_VIOLATED_SIGNAL
       as SIGBUS.

       There  are,  without doubt, other bugs and porting issues. Please contact me via e-mail if
       you have any bug reports, ideas, etc.

WHAT'S BETTER
       Purify does a much more thorough job than Electric Fence, and does not have the huge  mem-
       ory  overhead.	Checkergcc, a modified version of the GNU C Compiler that instruments all
       memory references, is available on Linux systems and where GCC is used. It  performs  some
       of the same tasks as Purify, but only on code that it has compiled.

					  27-April-1993 				efence(3)


All times are GMT -4. The time now is 06:47 AM.

Unix & Linux Forums Content CopyrightŠ1993-2018. All Rights Reserved.
UNIX.COM Login
Username:
Password:  
Show Password