Checker V0.3  (c) 1993,1994 Tristan Gingold
Checker will be a free and GNU implementation of Purify(tm).

If you don't know what Checker is, please read the INTRO file.

How do I compile Checker?
 Look in config.h and change it if you need to.
 Now type:
 % make dep
 % make

 This will make libchecker.o.
 To install, see the INSTALL file.

What's in the patches dir?
 The patches directory contains changed files from packages used to build
 tools in Checker. See the patches/README file for more information 
 conserning these changes.
 
 You don't actually have to build a new GAS or the other tools checker
 uses, but the patches are there should you decide to.

Questions and Answers:
----------------------

When I link Checker with my program, I get a link error:
   "Undefined symbol chkr_?_?_?_?_chkr referenced from text segment", where
   '?' are numbers. Is it a bug?
 Not really. An address extractor function has not been defined. The changes
 are rather easy: just a line to add in addrextract.S. Send me mail about
 this so I can fix it please. 

When I kill a program linked with Checker, some files appear in /tmp.
 Checker creates some temporary files in /tmp containing the symbol
 table from your binary.  Checker usually deletes these, but sometimes it 
 can't.  So, remove them.

When I compile Checker, gcc fails on find_exec.c
 Compile find_exec.c without the -O option.

What is 'symctl' ?
 The binary (symctl) controls which symbols are exported.  This is used
 by libchecker.o so defined symbols such as 'strcmp' will not be used by
 your program.

What are the differences between GAS v2.2 and GAS v1.38?
 GAS v2.2 works perfectly (the linux kernel and libc have been compiled 
 with it).  The only incompatibility is that GAS v2.2 doesn't allow
 the '//' comment so you'll have to change '//' to '#'.
 
What are the new options of GAS?
 When patched to work with Checker, you can use the following options with
 GAS:
 -checker 		: insert code
 -nochecker 		: normal mode
 -checker-verbose 	: insert code and tell where
 -checker-nostack	: do not insert code on stack instructions.

Sometimes Checker detects a memory access error in a libc.a function. Does 
this mean the libc.a library is buggy? 
 Perhaps, but please check that you don't call a function from libc.a 
 with a bad pointer before you assume the library is buggy.

What does the environment variable CHECKEROPTS do?  How can I give options 
to a checkered program at run time?
 There is an environment variable, CHECKEROPTS, which a program compiled
 under checker will read to set command line options as if they were 
 actually typed on the command line when the program was run.
 To set CHECKEROPTS, use (csh): setenv CHECKEROPTS "..."
		         (sh) : export CHECKEROPTS="..."
 Options are:
	-s --silent          Do not print the welcome message.
	-q --quiet           idem.
	-a --abort           Stop immediately.
	-h --help            Print this message.
	-n --nosymtab        Do not use symbol table.
	-o=file --output=file  Redirect the output error of Checker to 'file'.
	-i=file --image=file Set the image file (Checker find it for you)
	-p --profile         Display profile informations.
	-d=x-y --disable=x-y disable x-y (don't display for warning if error)
			     '-y' is optional
        -S --stop            stop just before main with kill -STOP pid.

How to use ~/.checker ?
The grammar is simple: each line contains a file-name and options.
If the file-name is the program name, Checker reads the options.
Comment are introduced by a '#' in the first column.
A file-name is the program name if:
o  it is the full path (./ ../ and // are eliminated)
o  it is argv[0]
o  it is the basename
o  it is 'default'
Example:
# a comment
try -S --help
./try -p
default -p
If your program is run with './try', all option will be accepted.

How to use other language:
 Try make LANG=French
 Currently, only the French and English languages are implemented.
 If you want to use other language, you have to translate:
 create a new directory in ./config, copy files from English (e.g.) and 
 translate.

What is insertor?
 insertor will be a new way to insert code: it will read a .o file and
 directly inserts code. It is not finished. See also doc/NewFormat.

I can't link a checkered program with libxxx.a ?
If libxxx.a is yours, and have been compiled with Checker, rename it to
	libxx.chkr.a 
If libxxx.a is a standard library, you can't and mustn't link it with a
	checkered program. You have to compile the library with Checker.
	If you were able to link a standard library, this standard library
	would not be able to find memory access error, and would not be able
	to update the memory map, so that Checker would display incorrectly
	access error.

If you want to port Checker:
 There are 3 machine dependent files: machine.c, sysdep.c and codecheck.S
 There are symbolic links to files located in config/*
   o symtab.c is OS dependent. It depends on the format of 
     the executable file.  At this time, only (GNU) a.out is 
     recognized (config/obj-formats/gnu.a.out.c)
   o machine.c is OS and CPU dependent. It depends on the memory organisation,
     the stack organisation...  At this time, only Linux is recognized 
     (config/i386/Linux/linux.c) 
   o codecheck.S is CPU dependent. It is called by the code inserted, 
     computes the address and calls chkr_check_addr().

Changes against Checker V0.1e-7:
	* Implementation of bitmaps and code insertion
	* Bug in the garbage collector fixed (Thanks to linus@lysator.liu.se)
	* chkr_save_stack is more robust. It should never make dump core (Thanks
	    to Warner Losh imp@Boulder.ParcPlace.COM for his patch)

Changes against Checker V0.1:
	* implementation of bitmaps on stack segment
	* bug of movsbl, movswl, ... is fixed
	* forgotten chkr_?_?_?_?_chkr added (multiple thanks)
	* realloc & calloc bugs fixed (Thanks to humberto@annexstein.csm.uc.edu)
	* a better way to use the libraries is implemented: all Checkered
	  libraries must have .chkra suffix, and 'ld' is modified to read them 
	  when -checker option is used
	* check of syscall is made inside checker rather than inside libc.a
	* Checker is initialized by chkrcrt0.o
	* bug of S-i-b addressing mode without base is fixed
	* 'or' & 'and' instructions now check only for writting. This allow bit
	  accesses
	* morecore.c is merged with maccess.c 
	* valloc & memalign protect lost memory
	* At the end of 'free', chkr_set_right was called, even if there was
	  an error. This bug is fixed.
	* options at running time by CHECKEROPTS var.

Changes against Checker V0.2:
	* export is replaced by symctl. More clean.
	* __chkr_trap is called only by chkr_vprintf. => more clean
	* chkr_find_executable now handles correctly PATH beginning with a
		':' (i.e. current directory). (Thanks to joe@nimbus.muc.de)
	* 'profile' option added
	* Faster organisation for MapInfo.
	* handle -N (pure) executable. Text is writable.
	* always check the image file is correct.
	* -i=file --image=file options added
	* stack frames are printed from stored info and not from relative
		frames. faster, more precise and more clean.
	* imulKludge bug fixed as well as call/jmp with modrm.
	* use GAS V2.2 instead of GASV2.1.1 (seems to be faster)
	* little bug in vprintf fixed (was a '%2d' bug)
	* display bug for b-malloc/garbage.c:disp_leaks(520) fixed
	* new organization of files: all config files are in ./config/
	* lseek now works. (was a stupid bug)
	* fcntl(x,F_SETFD,y) , read(x,y,0), execve() and strlen() are now OK.
	* allow local languages (i.e. French and English are available)
	* use a new malloc, with 'aged' (just freed) blocks.
	* syscall checks updated. (Linux 99pl14)
	* symtab loaded by mmap -> more available, faster.
	* asm operands fstsw, fstcw, fldcw are now OK.

Changes against Checker V0.3
	* stosb and movsb instruction are handled.
	* alarm(2), pause(2) (???), time(2), readlink(2) and select(2) work.
	* Check_addr is not called by macro in addrextract.S -> faster
	* add -disable=x-y option.
	* write info at the end of the temp files.
	* add -stop option.
	* support signals.
	* better to support options; options with ~/.checker file.
	* bug in chkr_2_6_2_4_chkr fixed.
	* bug in calloc.c fixed.
	* chkr_2_3_0_2_chkr created for movsw.
	* bad calls to chkr_copy_bm in realloc fixed.
	* handle std/cld -> now bcopy is OK.
	* prevent from reexecuting __chkr_init_chkr.
	* call and push %ebp create a red zone.
	* asm operand fstsw, fstcw and fldcw are checked with only 16 bits.
	* symctl display unknown imported symbols.
	* l-malloc/maccess.c: add const to chkr_check_* and ...
	* crt0.s updated to set correctly the rights on the stack.
	* chkr_out fd is tested and reopen if necessary.
	* malloc, free, etc check their arguments are readable.
	* some errors with fcntl() fixed.
	* can now handle 10 bytes fp ops.
	* __setjmp(3) works correctly.
	* adjust_stackbitmap now works correctly (bug fixed).
	* add a flag by gas -> prevent from mixing .a and .chkr.a
	* little bug in l-malloc/malloc.c fixed.
	* a new chkr_show_addr -> symbols are now OK
