File:INTRO	Checker V0.6  (c) 1993, 1994 Tristan Gingold

  Hello!  This is the new version of Checker.  Checker is a debugging
tool suite which will find memory errors at runtime.  As most
programmers 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.6 of Checker is compatible with libmmalloc, suuports mmap,
munmap and shm and corrects severals bugs.
  Checker can now produce libmdchecker.a, a static library which is in fact
a malloc debugger and a garbage collector. Last but not the least, with
plchecker.o, you can run the garabge collector on an already linked program. 
See the README file for more information.

  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.

  The malloc library of Checker is very robust, this makes it 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 <malloc.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 */
	}

To compile:
% checkergcc -o example example.c

and then run the program:
% ./example
Checker version 0.6 Copyright (C) 1993,1994 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 '-h'
From Checker (pid:00440): The messages for './example' will follow.

From Checker (pid:00440): (ruh) read uninitialized byte(s) in a block.
When Reading 1 byte(s) at address 0x1682d, inside the heap (sbrk).
1 bytes into a block (start: 0x1682c, length: 20, mdesc: 0x0).
The block was allocated from:
	pc=0x00005d23 in _malloc() at ../l-malloc/malloc.c:188
	pc=0x00005d82 in malloc() at ../l-malloc/malloc.c:203
	pc=0x000010ba in main() at example.c:5
	pc=0x00001079 in __entry() at chkrcrt0.S:1
Stack frames are:
	pc=0x000010f0 in main() at example.c:10
	pc=0x00001079 in __entry() at chkrcrt0.S:1
From Checker (pid:00440): (bvh) block bounds violation in the heap.
When Reading 1 byte(s) at address 0x1682a, inside the heap (sbrk).
2 bytes before a block (start: 0x1682c, length: 20, mdesc: 0x0).
The block was allocated from:
	pc=0x00005d23 in _malloc() at ../l-malloc/malloc.c:188
	pc=0x00005d82 in malloc() at ../l-malloc/malloc.c:203
	pc=0x000010ba in main() at example.c:5
	pc=0x00001079 in __entry() at chkrcrt0.S:1
Stack frames are:
	pc=0x00001117 in main() at example.c:11
	pc=0x00001079 in __entry() at chkrcrt0.S:1
From Checker (pid:00440): (bvh) block bounds violation in the heap.
When Writing 1 byte(s) at address 0x16845, inside the heap (sbrk).
5 bytes after a block (start: 0x1682c, length: 20, mdesc: 0x0).
The block was allocated from:
	pc=0x00005d23 in _malloc() at ../l-malloc/malloc.c:188
	pc=0x00005d82 in malloc() at ../l-malloc/malloc.c:203
	pc=0x000010ba in main() at example.c:5
	pc=0x00001079 in __entry() at chkrcrt0.S:1
Stack frames are:
	pc=0x0000113e in main() at example.c:12
	pc=0x00001079 in __entry() at chkrcrt0.S:1
From Checker (pid:00440): (nza) null zone addressed.
When Writing 1 byte(s) at address 0x0, inside the NULL zone.
You probably deferenced a null pointer.
THIS SHOULD CAUSE A SEGMENTATION FAULT.
Stack frames are:
	pc=0x00001153 in main() at example.c:13
	pc=0x00001079 in __entry() at chkrcrt0.S:1
Segmentation fault

To see other features in Checker, see the testsuite/try_*.c files.

  Checker works only on Linux. 

NOTE: Checker works entirely through the assembler and the library
libchecker.o.  Checker therefore comes with its own versions of "as"
and "ld".  The "ld" avoids linking a checkered program with a
non-checkered library--to be found by the -l switch, checker-compiled
libraries must have names ending with '.chkr.a', instead of '.a').
These "as" and "ld" programs are only used when compiling with
Checker: they don't replace the ones which come with gcc.

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:
 Tristan C/O gingold@amoco.saclay.cea.fr
I can send you a reply during the weekend.

Checker could become a GNU package.

IF YOU GET Checker-0.6.tgz, YOU ALSO NEED Checker-libs-0.6.tgz.
You can also get Checker-libg++-0.6.tgz and Checker-Xlibs-0.6.tgz when they
will be available. (Don't use the old versions.)

Happy Checking.

Tristan.
