













   P     i     c     k     e     t           F     e     n     c     e

   /\    /\    /\    /\    /\    /\    /\    /\    /\    /\    /\    /\
  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |
  |  |--|  |--|  |--|  |--|  |--|  |--|  |--|  |--|  |--|  |--|  |--|  |
  |  |--|  |--|  |--|  |--|  |--|  |--|  |--|  |--|  |--|  |--|  |--|  |
  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |

                                 Version 1.4







Picket Fence malloc debugger v1.4

Licence:

  In this document, pfence means Picket Fence, a malloc-debugging
  utility.
  You may use pfence at your own risk. Using pfence does not guarantee
  that your code is bug-free, although pfence helps hunting down hard-
  to-find bugs from your code.
  You may distribute pfence in its whole, unmodified form, as long as
  it's not sold. You may include pfence in commercial CD-ROMs as long as
  the author is notified.
  You may not distribute modified versions of pfence, but the author
  would be intrested in any improvements you have made.
  If you used pfence, and pfence does not report any problems in your
  code, you must include the line: "Certified with Picket Fence v1.4" in
  either your program or its documentation.

Who did it?

  Jari Komppa aka Sol/Trauma, solar@compart.fi
  
What is it?

  Picket Fence is a run-time debugging utility to track down pointer-
  and memory allocation specific bugs, such as writing over table
  bounds, writing into already freed memory, etc. It can also be used to
  track down memory leaks, i.e. memory that is allocated but forgotten
  to be deallocated after use.

What is new in it ?

  Pfence 1.4 includes friendlier output (telling you, in most cases,
  where the crash occurs without the use of debugger), some fixes
  and more options.
  
What is it made for?

  Watcom C dos4gw-based applications, although it should work with
  almost any platform, and is tried and works under c++ as well, but is
  pretty useless unless you use malloc/free calls in c++ instead of
  new/delete.
  Under linux you should use libefence (electric fence) instead.


What does it do?

  It builds its own memory database, and creates a "fence" around your
  allocations, checking every once in a while whether you have written
  over or under such buffer. It may also check if you try to free a
  previously freed pointer (which may mean that you've been using it),
  and it may also track if you write into previously freed buffer.
  It also gives out a global variable which shows how much memory you
  have allocated. This can be used to track down memory leaks.

What it doesn't do?

  It doesn't track down illegal memory reads. It also checks the fences
  only when a call to malloc, free, realloc or pfence_checkmemtree is
  made. Reason for this is that DPMI 0.9, which is the target platform
  for Picket Fence, does not support memory protection control. Also,
  if your illegal memory writes don't hit any fence areas, pfence cannot
  know what happened.
  
  Picket Fence doesn't replace your clib:s memory allocation functions,
  thus if you use other memory-allocating functions such as strdup,
  these buffers will not be "fenced" and will cause error when freed
  under Picket Fence.
  Replacing all such functions with pfence_ versions would have been a
  wasted effort; you must work around this problem if you use such
  functions. (You might _nfree() these under Watcom, or build your
  own versions of such functions).
  
What does more?

  Electric Fence, under Linux (of which Picket Fence is an inferior
  clone) does its work with protected memory pages, and as such does
  very much better job.
  NuMega BoundsChecker is probably the ultimate utility for these kinds
  of problems.
  

Usage:

  Step one: (preparation)
  
    Link pfence.c into your program. Include the line:
    
      #include "pfence.h"
      
    AFTER standard library inclusions, and before any
    malloc/calloc/realloc/free call.
    
  Step two: (test run)
  
    Run your program. If it works flawlessly (although a lot more slowly
    due to pfence's checks), you're probably home safe. To be sure,
    include the line:
    
      pfence_checkmemtree();
      
    just before the exit from your program.
    If it works, just remove pfence from your program; your code is OK
    as far as Picket Fence can see.
    If not,
    
  Step three: (analyzing error)
  
    Recompile your code (all of it) with debugging options on. (Under
    Watcom, use -d2 or -d3 with wcc386/wpp386, and "debug all" with
    linker).
    Run it under debugger (watcom/dos4gw: wd /tr=rsi yourprog.exe).
    Place breakpoint at pfence.c function 'crash()' at the row that
    starts with printf().
    Run your program (watcom: f5). At break, check the variables
    'reason' and 'count'.
    
    The possible reason codes are:
    1 - malloc <=0
      (allocation call to allocate zero or less bytes; probably an
      arithmetic problem with your code)
    
    2 - out of memory
      (just what it says)
      
    3 - under trash
      (detected data written over the bottom fence)
      
    4 - over trash
      (detected data written over the upper fence)
      
    5 - free() call on unallocated non-null pointer
      (just what it says)
    
    6 - trashed 'freed' memory
      (detected data written on previosly freed memory)
    
    7 - crash on specified alloc number
      (see step four)


  Step four: (locating error)
    
    At this point you may already know what's wrong, but let's go on.
    Edit pfence.c, and find line starting with
    
      #define SPECIFIED -1
      
    Change the value after SPECIFIED to the 'count' from step three.
    Run your program under debugger just as in step three, including
    the breakpoint.
    Checking call stack, you should see where the violated memory was
    allocated, and see what variable it is.
    
    If it's still not clear where the violation occurs, start placing
      
      pfence_checkmemtree();
      
    calls in your code to see which part of the code crashes.
  
  That's it! Please check all the compilation options in pfence.c as
  well; you might find some of them useful in your bughunt.

  To locate memory leaks, you must add checks in your own code to check
  pfence_total_alloced -variable to see whether you're wasting memory.
  
Anything else?

  Send comments to solar@compart.fi. Thank you.
