File:INTRO	Checker V0.5  (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 you will be well rewarded for taking the time to learn
how to use Checker!

  Version 0.5 of Checker supports signals, can ignore certain types of
memory access error, and corrects severals bugs.
  If you link with file not compiled through Checker, Checker will work but
only some errors will be detected (Read/write from/to a red zone, block
violation)
  Futhermore, you can now compile C++ programs, since libg++ is provided
with the other libs.
  NOTA: chkr_garbage_detector() and chkr_evol_detector() are replaced by
__chkr_garbage_detector() and __chkr_evol_detector().

  Checker is a package designed to find memory access errors and bad 
usage of malloc at run time.  When Checker finds an error, it displays 
a warning along with the current stack frames.  For more information 
about this, see the example below.

  The malloc library of Checker is very robust; however, it is slower than 
GNU Malloc.  Robust means that you can't cheat malloc.  Checker warns you if
	o You call free or realloc before you malloc the memory block
	o You try to free an already free zone
	o You call free with a bad address (not returned by malloc, calloc
          or realloc)
Futhermore, Checker's malloc tries to be as secure as possible: when you free
a block, it becomes 'aged' and will be really freed after n calls to free in
order to catch bugs where you access a block after it has been freed and 
when you try to free a block more than once.

Checker implements a garbage detector that can be called either in your 
program or by a debugger, such as gdb.  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.o example.c -c
% checkergcc -o example example.o

and then run the program:
% ./example
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:861)
Memory access error: (ruh) read uninitialized byte(s) in a block.
When Reading 1 byte(s) at address 0x122ad, inside the heap.
The block is 20 bytes length and starts at 0x122ac
1 bytes after the begin of the block
The block was allocated from:
	pc=0x00003bdc in _malloc() at ../Checker-0.5/l-malloc/malloc.c:163
	pc=0x00003c38 in malloc() at ../Checker-0.5/l-malloc/malloc.c:179
	pc=0x0000009a in main() at example.c:5
	pc=0x00000050 in __entry() at chkrcrt0.S:1
Stack frames are:
	pc=0x000000cc in main() at example.c:10
	pc=0x00000050 in __entry() at chkrcrt0.S:1
From Checker: (pid:861)
Memory access error: (bvh) block bounds violation in the heap.
When Reading 1 byte(s) at address 0x122aa, inside the heap.
The block is 20 bytes length and starts at 0x122ac
2 bytes before the begin of the block
The block was allocated from:
	pc=0x00003bdc in _malloc() at ../Checker-0.5/l-malloc/malloc.c:163
	pc=0x00003c38 in malloc() at ../Checker-0.5/l-malloc/malloc.c:179
	pc=0x0000009a in main() at example.c:5
	pc=0x00000050 in __entry() at chkrcrt0.S:1
Stack frames are:
	pc=0x000000ef in main() at example.c:11
	pc=0x00000050 in __entry() at chkrcrt0.S:1
From Checker: (pid:861)
Memory access error: (bvh) block bounds violation in the heap.
When Writing 1 byte(s) at address 0x122c5, inside the heap.
The block is 20 bytes length and starts at 0x122ac
5 bytes after the end of the block
The block was allocated from:
	pc=0x00003bdc in _malloc() at ../Checker-0.5/l-malloc/malloc.c:163
	pc=0x00003c38 in malloc() at ../Checker-0.5/l-malloc/malloc.c:179
	pc=0x0000009a in main() at example.c:5
	pc=0x00000050 in __entry() at chkrcrt0.S:1
Stack frames are:
	pc=0x00000112 in main() at example.c:12
	pc=0x00000050 in __entry() at chkrcrt0.S:1
From Checker: (pid:861)
Memory access error: (nza) null zone addressed.
When Writing 1 byte(s) at address 0x0, inside the NULL zone.
You probably use a NULL pointer.
THIS SHOULD PRODUCE A SEGMENTATION FAULT.
Stack frames are:
	pc=0x00000127 in main() at example.c:13
	pc=0x00000050 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 libchecker.o. So, I 
provide a new as, and a new ld. This new ld prevent you from linking your 
checkered program with a non checkered library (The libs must ended with 
'.chkr.a', instead of '.a').
These as and ld are only used when you compile with Checker: they don't
replace your old one.

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-V0.5.tgz, YOU ALSO NEED Checker-libs-V0.5.tgz.
You can also get Checker-Xlibs-V0.4.tgz.

Good Checks.

Note that the email address has changed.
Tristan.
