Provided by: electric-fence_2.2.5_amd64 bug


       efence - Electric Fence Malloc Debugger


       #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);

       int posix_memalign (void ** memptr, size_t alignment, size_t size);

       void * valloc (size_t size);

       extern int EF_DISABLE_BANNER;

       extern int EF_ALIGNMENT;

       extern int EF_PROTECT_BELOW;

       extern int EF_PROTECT_FREE;

       extern int EF_ALLOW_MALLOC_0;

       extern int EF_FILL;


       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

       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
       segmentation 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.


       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  will  cause  Electric  Fence  to be loaded to run all dynamic
       executables.  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
       operating  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
       program 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
       statement, and repair it.


       Electric  Fence  has  six  configuration  switches  that  can  be  enabled  via  the shell
       environment, 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.

              This is an integer which if nonzero specifies that the usual Electric Fence  banner
              and  copyright  notice  should  not  be  printed.   This  is  provided  for certain
              circumstances where the banner can be annoying (eg, running a regression test suite
              that  also monitors stderr).  Note that you should almost certainly not set this in
              your program,  because  then  you  might  leave  Electric  Fence  linked  into  the
              production version, which would be very bad.

              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
              allocation  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_ALIGNMENT 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.

              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
              inaccessible  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.

              When EF_PROTECT_FREE is not set (i. e. set  to  0),  Electric  Fence  returns  free
              memory  to  a  pool  and only checks accesses to it until it is reallocated. If you
              suspect that a program may be touching free memory, set EF_PROTECT_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.

              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_ALLOW_MALLOC_0 in the shell  environment  to  an  integer  value,  or
              assign to the global integer variable EF_ALLOW_MALLOC_0 using a debugger.

              When  set  to  a  value  between  0  and  255,  every  byte  of allocated memory is
              initialized 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 systems) and some memory will retain the values written to it during its  last


       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
       segmentation  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
       valloc() 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
       single 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


       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.


       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.


       Bruce Perens


       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.


       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.


       Bruce Perens
       1563 Solano Ave. #349
       Berkeley, CA 94707
       Telephone: 510-526-1165


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


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


       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.


       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.


       Purify does a much more thorough job than Electric Fence,  and  does  not  have  the  huge
       memory  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)