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

If you don't know what Checker is, please read the INTRO file.
To compile Checker, see the INSTALL file.
To know what is in the patches dir, see the patches/README file.

What does the environment variable CHECKEROPTS do?
How can I control the behavior of Checker at run time?

   The environment variable CHECKEROPTS and the file ~/.checker may be
   used to give Checker a set of options.  These options are read by
   the Checker library when a Checker-compiled program is run.

   To set CHECKEROPTS with csh, use: setenv CHECKEROPTS "..."
   To set CHECKEROPTS with sh, use:  export CHECKEROPTS="..."

   Options are:
	-s --silent          Do not print the welcome message.
	-q --quiet           Same as --silent.
	-a --abort           Abort on startup.
	-h --help            Print this message.
	-n --nosymtab        Do not use symbol table.
	-o=file --output=file  Redirect Checker's output to 'file'.
	-i=file --image=file Set the image file (Checker finds it for you)
	-p --profile         Display profile information.
	-d=xx --disable=xxx  Disable an address or a range of addresses.
	-S --stop            Stop just before main.
	-D=end --detector=end    Do leak detection at the end of the program.
	-m=a --malloc0=a     Set the behavior of malloc(0). 'a' can be:
				'warning' != 'no-warning': display a warning
				'0': ANSI behavior: returns 0.
				'1': malloc(0) is treated as malloc(1).
	-v --verbose         Verbose
        -u=end --inuse=end   Do inuse at the end.
         --sig-warn=sig      Emit a warning when sig is caught
   

How do I use the ~/.checker file?  

   ~/.checker is composed of groups of options, separated by a blank line.
   Every group begins with a line of filenames separated by a '|', without
   any blanks.  Then follow lines of options, each line of options begins
   with a tab.

   Lines starting with the '#' character are comments.

   A filename matches the program name if:
	o  the filename is the full path of the program 
	   (ignoring occurrences of ./ ../ and // in the full path)
        o  the filename is argv[0]
	o  the filename is the last component of argv[0]
	o  the filename is "default"

   Example:
	# a comment
	try|./try
		--help

	/tmp/try
		-S

	default
	# set --profile
		-p --detector=end

   If a program is run with './try', options '-p', '--detector' and '--help'
   will be used.  Moreover, if the program is in '/tmp', the '-S' option
   will also be enable.


How do I disable certain types of memory access error?

   Use the '-d=aaa' or '--disable=aaa' option in the CHECKEROPTS
   environment variable or the ~/.cheker file.  'aaa' is the the error
   type, which consists of three lower-case letters.  When Checker
   reports a memory access error, in includes the error's type in
   parenthesises before the description of the error.

   The error types are:
	(iei) internal error: instruction unknown.
	(nza) null zone addressed.
	(wro) write/modify read-only byte(s).
	(bvh) block bounds violation in the heap.
	(rfb) read in a free block.
	(wfb) write/modify a free block.
	(ruh) read uninitialized byte(s) in a block.
	(rus) read uninitialized byte(s) in the stack.
	(rsz) read on a red zone in the stack.
	(wzs) write on a red zone in the stack.
	(wus) modify uninitialized byte(s) in the stack.
	(mzs) modify a red zone in the stack.
	(nma) no memory addressed.
	(bvm) bounds violation in mapped memory.
	(apd) access permission denied in mapped memory.
	(wrs) write in a read-only shared memory.
	(zne) zone not executable.
	(sbv) segment bound violation.
	(fba) free called with an address not obtained from malloc.
	(ffb) free an already free block.
	(sba) sbrk called with a bad offset.
	(fbm) free called before malloc.
	(oom) warning: virtual memory exhausted.
	(mna) memalign called with a null alignment.
	(mba) alignment is not a power of 2.
	(ieb) internal error while checking.
	(bbs) bad bytes_per_state value. Used default value.
	(bkc) brk/sbrk has been called.
	(oos) out of system memory.
	(brs) bad red zone size.
	(tms) too many signal catched at the same time.
	(ies) internal error: can't check this syscall.
	(bfd) file descriptor reserved by Checker is used.
	(sfd) the system has resturned a file descriptor reserved by Checker.
	(ick) internal check.


When I kill a program linked with Checker, some files are left in /tmp.

   Checker creates some temporary files in /tmp containing the symbol
   tables from the program.  Checker usually deletes the files on
   program exit, but sometimes it doesn't get a chance to.  These
   files may be safely removed.


What is 'symctl' ?

   The program (symctl) controls which symbols are exported from an
   object file.  This is used by libchecker.o to prevent some
   internally used non-instrumented functions, such as 'strcmp', from
   being used by the instrumented program.


Sometimes Checker detects a memory access error in a libc.a function. Does 
this mean the libc.a library is buggy? 

   This is possible, but it more likely that a libc function was
   called with a bad pointer.


How to use other languages:

   Compile Checker with 'make LANG=French'

   Currently, only the French and English languages are implemented.
   If you want to use yet another language, create a new directory in
   ./config, copy the files from (e.g.) English, and translate them.


How could I port Checker to another system?

   See doc/checker.texi for more information.  If you are a GCC hacker,
please email me.

*********************
* Note for Sun users:
*********************

Checker has been ported to Solaris 2.x for SPARC.
Using Checker on Sun is very easy: compile your program as usual (it is a
good idea to use -g), link it as usual.  You can now run it.
You can also run it with Checker:
% checker ./a.out
Very, very simple.
Checker can work with all programs.

How does it works ?
`checker' set LD_PRELOAD with checker.so.1 and exec your program. 
checker.so.1 contains a simulator.  As a result, your program runs slower,
but since it is your work, you can admire it longer :-)

At this time, Checker doesn't support multi-threaded programs, a lot of
syscalls, and ioctl features are not implemented.  Sometimes it can be really
easy, sometimes it can be a little bit harder to implement them.

To install Checker, see INSTALL.


***********************
* Note for Linux users:
***********************

Two versions of Checker are available on Linux:
	* the a.out version which only works with a.out binaries.
	* the ELF version which only works with ELF binaries.
`configure' choose the version according your default gcc configuration.
To know your default configuration, compile a simple program with gcc -v.
`ccp' displays one line such as:
  `GNU CPP version 2.7.2 (i386 Linux/ELF)'    --> ELF
  `GNU CPP version 2.7.2 (80386, BSD syntax)' --> a.out
If you want to choose the other version of Checker, simply do:
   > setenv CC "gcc -b i486-linuxaout"
   > ./configure
There are some differences between the both versions.
Be very careful with the ELF version: since I use the standard linker, I
don't prevent to mixing non-compiled-through-Checker-files and
compiled-through-Checker-files.  If you mix them, you will discover a weird
world... :-)

For linux-* users:
******************
When I link Checker with my program, I get a link error:
"Undefined symbol chkr_?_?_?_?_chkr referenced from text segment",
where the '?' are numbers.

   Send me mail about the omission so I can fix it in the next release.


What are the new options of GAS?

   Try /usr/(local)/lib/checker/as --help

For linux-aout users:
********************
Is it possible to use Checker on some part of a project, by
only recompiling some sources and not others?
   Yes, though this disables a large number of checks.  If there is
   any part of a program which is not compiled with Checker, it
   cannot tell whether certain types of memory locations are valid or
   not.


I can't link a checkered program with libxxx.a ?

   If libxxx.a is yours, and has been compiled with Checker, rename it
   to libxx.chkr.a

   If libxxx.a is a standard library, see previous questions.


For linux-ELF users:
********************
Is it possible to use Checker on some part of a project, by
only recompiling some sources files?
   No.

Is it possible to use shared libraries with Checker?
   No.  You have to patch my patches for GAS.  However, such a shared
library would really be slow, due to the high number of calls.

BE CAREFUL: Checker for linux-elf doesn't mark binaries compiled through
Checker.  As a result, you can easily mix binaries compiled through Checker
and binaries not compiled through Checker.  This will produce no warnings
but results will be weird.
