File:README	Checker (c) 1998 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!

  For information about the latest features of Checker, see file NEWS.

  Currently, Checker works on:
	* i586-pc-linux-gnu
	* sparc-sun-solaris2.5

WARNING - WARNING - WARNING - WARNING - WARNING - WARNING - WARNING - WARNING
This is an alpha version.  As a result, bugs might remain in the code.

INSTALLATION: Read INSTALL file.

  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 only 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.9 (sparc-sun-solaris2.5.1) Copyright (C) 1998 Tristan Gingold.
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:04713): `./example' is running (Sun Jan 18 14:56:49 1998)

From Checker (pid:04713): (ruh) read uninitialized byte(s) in a block.
When Reading 1 byte(s) at address 0x000398a1, inside the heap (sbrk).
1 bytes into a block (start: 0x398a0, length: 20, mdesc: 0x0).
The block was allocated from:
	pc=0x00022f1c in chkr_malloc() at ../stubs/stubs-malloc.c:51
	pc=0x0001339c in main() at ../example.c:7
	pc=0x000155f0 in startup() at ../config/sparc/solaris2/startup.c:148
	pc=0x00013298 in *unknown*() at *unknown*:0
Stack frames are:
	pc=0x000133f4 in main() at ../example.c:12
	pc=0x000155f0 in startup() at ../config/sparc/solaris2/startup.c:148
	pc=0x00013298 in *unknown*() at *unknown*:0
From Checker (pid:04713): (bvh) block bounds violation in the heap.
When Reading 1 byte(s) at address 0x0003989e, inside the heap (sbrk).
2 bytes before a block (start: 0x398a0, length: 20, mdesc: 0x0).
The block was allocated from:
	pc=0x00022f1c in chkr_malloc() at ../stubs/stubs-malloc.c:51
	pc=0x0001339c in main() at ../example.c:7
	pc=0x000155f0 in startup() at ../config/sparc/solaris2/startup.c:148
	pc=0x00013298 in *unknown*() at *unknown*:0
Stack frames are:
	pc=0x00013434 in main() at ../example.c:13
	pc=0x000155f0 in startup() at ../config/sparc/solaris2/startup.c:148
	pc=0x00013298 in *unknown*() at *unknown*:0
From Checker (pid:04713): (bvh) block bounds violation in the heap.
When Writing 1 byte(s) at address 0x000398b9, inside the heap (sbrk).
5 bytes after a block (start: 0x398a0, length: 20, mdesc: 0x0).
The block was allocated from:
	pc=0x00022f1c in chkr_malloc() at ../stubs/stubs-malloc.c:51
	pc=0x0001339c in main() at ../example.c:7
	pc=0x000155f0 in startup() at ../config/sparc/solaris2/startup.c:148
	pc=0x00013298 in *unknown*() at *unknown*:0
Stack frames are:
	pc=0x0001345c in main() at ../example.c:14
	pc=0x000155f0 in startup() at ../config/sparc/solaris2/startup.c:148
	pc=0x00013298 in *unknown*() at *unknown*:0
From Checker (pid:04713): (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=0x0001347c in main() at ../example.c:15
	pc=0x000155f0 in startup() at ../config/sparc/solaris2/startup.c:148
	pc=0x00013298 in *unknown*() at *unknown*:0
From Checker (pid:04713): (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:
 bug-checker@gnu.org
(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.
