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

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

How do I compile Checker?
 See 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 
 concerning 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:
----------------------
How can Checker be used ?

  Checker can be used in tree ways:

   libmdchecker.a is a dropin replacement for the standard malloc of libc.
   Just insert /usr/lib/checker/libmdchecker.a in your link
   command. This malloc will show some misuse of malloc and free
   such as freeing a block twice, or a bloc which was never
   malloced. libmdchecker.a feature also other capabilities such
   as a mean to locate orphan block (block never freed). You have to create
   libmdchecker.a with 'make libmdchecker.a'. Use it as a standard library:
   % gcc -o my_prog my_prog.o -lm libmdchecker.a
   You must have a patched vesion of ld.so. See Checker/bin/README

   plchecker.o can be used as a preloaded object. To use it, just do:
   % setenv LD_PRELOAD /my_path/plchecker.o
   % ls (or any program)
   You have to create plchecker.o with 'make plchecker.o'.  You also must
   have installed the patched version of ld.so. See Checker/bin/README

   The last way is to compile all the code in a program with
   checkergcc.  To do this, the modified versions of as and ld must be
   installed.  Checker will insert code into the compiled program to
   validate all memory references.  Simply execute the result and
   watch the show.  See the examples in testsuite/*.c

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.


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).
   

How do I use the ~/.checker file?  

   The grammar of the ~/.checker file is simple: each line contains a
   filename and options.  If the filename matches the name of the
   checker-compiled program, Checker reads the options.

   Lines starting with the '#' characer 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 -S --help
	./try -p
	default -p

   If a program is run with './try', all options will be used.


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 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.

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.

Why not open this file and immediatly unlink() it?
   
   Imagine the user close this fd and reopen it...

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.

What are the new options of GAS?

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


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.


What is insertor?

   Insertor will be a new way to insert code: it will read a .o file
   and directly insert the instrumentation code. It is not finished.


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.

How would I port Checker to another system?

   There are machine dependent files: machine.c, sysdep.c and codecheck.S
   There are symbolic links to thes 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 organization,
     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 addresses being accessed, and calls chkr_check_addr().

Changes since 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 since 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 since 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 since 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 infos at the end of the temp files.
	* add -stop option.
	* support signals.
	* support options better; can use ~/.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.

Changes since Checker V0.4
	* symctl -c obj -> strip: remove symbols unused by checker.
	* check the fd used by checker are not handled by the program.
	* sbrk(3) can be used. (But not intensively tested)
	* ioctl(a,FIONREAD,b) fixed.
	* some ioctls added.
	* configure script added and Makefiles changed.
	* maccess.m, parse-args.m added and dmstring.m supressed.
	* line numbers in stack frames are now ok. (Thanx to bas@phys.uva.nl)
	* (chkrcrt0.S): add a stabd.
	* (specs): doesn't allow -fomit-frame-pointer.
	* signals are now well supported.
	* wait4(2), getgroups(2), readlink(2), recv(2) now work correctly.
	* klog(2) now works.
	* bug in simplify_path corrected (was xxx/zzz/../ttt ).
	* emit a warning when virtual memory is exceeded.
	* (free.c:find_header): add SOFT arg, used by maccess.c
	* genmess: add $comment command, and '-' as headerfile.
	* memory access error message are more informative.
	* checker can ignore certain type of memory error.
	* display the pid before each error.
	* close(2) and dup(2) aren't executed if FD is used by Checker.
	* chkr_1_5_1_1_chkr created for popa.
	* ld: allow to link with normal files and set ___chkr_ld_opts__ flag.
	* maccess.c: disable stack check when ___chkr_ld_opts__ is set.
	* parse-args.c: emit a warning when normal files are used.
	* parse-args.c: new option -D=end: do a garbage detector at the end.
	* with '--malloc0=' option, you can change the behavior of malloc(0).
	* ipc syscalls checks are now implemented, except shm.
	* bugs corrected in chkr_1_5_0_4_chkr.

Changes against Checker V0.5
	* (sys_realloc): now is OK with memcpy.
	* mmap, unmap are now working.
	* shm* are now working.
	* (lib/mktemp.c, lib/vprintf.c, parse-args.c): pid stored.
	* specifications for the output file name (pid: %p, progname: %n)
	* (garbage.c): doesn't use POINT_JUST_SEEN anymore.
	* (garbage.c): sure leaks are now really sure.
	* (smalloc.c): abort if out of memory.
	* (config/i386/Linux/sigsend.c): Several bugs fixed.
	* (find-exec.c): rewritten.
	* Signals are now better supported.
	* (gas) casting a float to an int doesn't generate a report.
	* (setchkrfl): more powerful (--yes, --no or question).
	* (bitops.h): more generic.
	* reports are harmonanized.
	* ioctls for network supported.
	* fcntls which don't use a third argument are now working.
	* (parse-args.c): -o=+file to append.
	* (maccess.c): the stack bitmap is now normal.
	* sbrk(0) now produces no warning.
	* emit report in case of a bad call/jump.
	* (codecheck.S): bug with Lsemovsl fixed.
	* the internal system calls now use chkr_errno instead of errno.
	* maccess.c (__chkr_disp_map): new.
	* maccess.c (__chkr_pause): new.
	* linux-syscall.c: gettimeofday() is now OK.
	* smalloc.c (sys_malloc): spliting a block now set MD_BUSY.
	* codecheck.S (chkr_0_6_1_a_chkr) (chkr_0_6_2_a_chkr): added.
	* maccess.c (get_total_mem): new.
	* macc-mmap.h: the data bitmap is really suppressed.
