File:README	Checker V0.8  (c) 1993, 1994, 1995, 1996 Tristan Gingold

  Hello!  This is the new version of Checker.  Checker is a debugging
tool suite which find memory errors at runtime.  As most programmers should
know, runtime memory errors are difficult to track down;
therefore, it is likely that programmers will be well rewarded for
taking the time to learn and use Checker!

  Version 0.8 of Checker is a transitional version: Checker 0.7 was very
machine dependant and difficult to port whereas Checker 0.9 will use a
new flag of GCC: -fcheck-memory-usage.  As a consequence, it won't use anymore
a patched version of AS and a checkered library, but stubs.  Futhermore, it
will be faster, do not produce bad warnings (structure assignments will work),
and will really more portable.
  Version 0.8 use the 0.7 mechanism by default, but it include a patch for
gcc-2.7.2 so that you can use the 0.9 mechanism if you want (See
README.BETA).

  Currently, Checker 0.8 works on:
	* Sparc Solaris 2.5 (SparcStation20, IPC, IPX but not Ultra).
	* i386,i486,i586,i686 linux.
 
  See the doc if you want to port it on other machines and email me if you
are still interested.

  Checker is a package designed to find runtime memory access errors
and incorrect use of malloc().  When Checker finds an error, it
prints a warning, including the current stack frames.  For more
information about this, see the example below.

  Checker works for C.  C++ was not tested.

  The malloc library of Checker is very robust, this makes it a bit slower
than GNU Malloc.  Checker issues warnings when:
        o free() or realloc() is called with a pointer that has not been
          obtained from malloc(), calloc(), or realloc()
        o free() or realloc() is called with a pointer that has been
          previously freed.
Checker's malloc will refrain from reusing a freed block for some
additional number of calls to free.  It does this in order to catch
accesses to the block after it has been freed.

Checker implements a garbage detector that can be called either in
your program, by a debugger such as gdb, or upon program exit.  The
garbage detector displays all the memory leaks along with the
functions that called malloc().

EXAMPLE:
Here's a bogus file example.c
	#include <stdlib.h>

	int
	main ()
	{
	 char *zone = malloc (20);
	 char *ptr = NULL;
	 int i;
	 char c;

	 c = zone[1];		/* error: read an uninitialized char */
	 c = zone[-2];		/* error: read before the zone */
	 zone[25] = ' ';	/* error: write after the zone */
	 *ptr = 2;		/* error: use a NULL pointer, must produce a core */
	}

  Compile:
  % checkergcc -o example example.c
  and then run the program:
  % ./example

Checker 0.8 (i486-unknown-linux) Copyright (C) 1996 Tristan Gingold.
This program has been compiled with `checkergcc' or `checkerg++'.
Checker is a memory access detector.
Checker 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.  See the GNU
General Public License for more details.
For more information, set CHECKEROPTS to `--help'
From Checker (pid:00633): `./example' is running (Sat Oct 12 14:52:40 1996)

From Checker (pid:00633): (ruh) read uninitialized byte(s) in a block.
When Reading 1 byte(s) at address 0x08063271, inside the heap (sbrk).
1 bytes into a block (start: 0x8063270, length: 20, mdesc: 0x0).
The block was allocated from:
	pc=0x080518d0 in malloc() at ../l-malloc/malloc.c:251
	pc=0x080481dc in main() at ../example.c:7
	pc=0x0804810c in _start() at :0
Stack frames are:
	pc=0x0804820e in main() at ../example.c:12
	pc=0x0804810c in _start() at :0
From Checker (pid:00633): (bvh) block bounds violation in the heap.
When Reading 1 byte(s) at address 0x0806326e, inside the heap (sbrk).
2 bytes before a block (start: 0x8063270, length: 20, mdesc: 0x0).
The block was allocated from:
	pc=0x080518d0 in malloc() at ../l-malloc/malloc.c:251
	pc=0x080481dc in main() at ../example.c:7
	pc=0x0804810c in _start() at :0
Stack frames are:
	pc=0x08048231 in main() at ../example.c:13
	pc=0x0804810c in _start() at :0
From Checker (pid:00633): (bvh) block bounds violation in the heap.
When Writing 1 byte(s) at address 0x08063289, inside the heap (sbrk).
5 bytes after a block (start: 0x8063270, length: 20, mdesc: 0x0).
The block was allocated from:
	pc=0x080518d0 in malloc() at ../l-malloc/malloc.c:251
	pc=0x080481dc in main() at ../example.c:7
	pc=0x0804810c in _start() at :0
Stack frames are:
	pc=0x08048254 in main() at ../example.c:14
	pc=0x0804810c in _start() at :0
From Checker (pid:00633): (nza) null zone addressed.
When Writing 1 byte(s) at address 0x00000000, inside the NULL zone.
You probably deferenced a null pointer.
THIS SHOULD CAUSE A SEGMENTATION FAULT.
Stack frames are:
	pc=0x08048269 in main() at ../example.c:15
	pc=0x0804810c in _start() at :0
From Checker (pid:00633): (sig) signal.
Receive signal 11 (SEGV): (default action: terminate core ).
Segmentation fault

For more information, see the NOTES and doc/checker.texi files.

If you like Checker, use it and try to find bugs....
If you find a bug, have a suggestion, dislike Checker, want to make it
better, want to port it, or find an English mistake, email me at:
 gingold@email.enst.fr
(Note my new address.  BTW, I cannot read mails posted to my old address,
so, please send them to my new address if you didn't get an answer.

Happy Checking.

Tristan.
