Bounds Checking Patches for GCC 2.7.1
-------------------------------------

By Richard W.M. Jones <rwmj@doc.ic.ac.uk>
Version: 1.0

What is bounds checking?
------------------------

These patches give very fine-grained bounds checking, catching errors in
C programs like this one:

	int i;
	char array[10];

	for (i = 0; i <= 10; ++i)
	  array[i] = 0;

(Notice element array[10] is not part of the array). The patches are
compatible with almost all C constructs. For instance, the following
programs have been successfully compiled with bounds checking:

	Tcl 7.3 & 7.4
	Tk 3.6 & 4.0
	Ghostscript 262
	uEmacs 3.10
	xrn
	GNU Grep 2.0
	XBoing 1.8

What files do you need?
-----------------------

You can install GCC with bounds checking either by compiling from the source,
or using one of the current binary distributions.

>> To compile from source, you need to retrieve:

	bounds-checking-2.7.1-x.y.tgz

   *plus* the source for GCC (which you may already have). One place you can
   find the source of GCC is:

	ftp://sunsite.doc.ic.ac.uk/gnu/

   You will need around 60 Mbytes of free disk space.

>> To install GCC binaries, you will need to retrieve:

	bounds-checking-2.7.1-x.y-binary-cpu-manufacturer-system.tgz

   (where cpu-manufacturer-system might be, for instance, `i486-unknown-linux')
   If you don't see a binary distribution for your particular machine, then
   you will need to compile from source (see above). You might consider
   sending me the binaries so I can put them on the FTP site.

   You do *not* need the source to GCC. You do *not* even need a C compiler.
   You will need a way of reading `info' files, though, if you want to read
   the supplied documentation.

How to compile GCC with bounds checking from source
---------------------------------------------------

Skip this section if you got a binary distribution.

Let's suppose, for the sake of example, that you've already placed a *fresh*
GCC source tree in `~/gcc-2.7.1'. Patch the tree as follows:

	cd ~/gcc-2.7.1
	make distclean			# Clean up source tree.
	zcat ~/bounds-checking-2.7.1-x.y.tgz | tar xvf -
	patch -p4 < bounds-checking.diff

Compile GCC as detailed in the file `INSTALL' that comes with GCC. Usually
you need to type:

	cd ~/gcc-2.7.1
	./configure			# Possibly some --options here.
	make

This also makes the bounds checking library (in the bounds/lib/ subdir.).
You'll need `makeinfo' (from the `texinfo' package) to make the info pages.

Installing a binary distribution
--------------------------------

To install in the directory `~/gcc-2.7.1' (for the sake of example), you
would do:

	mkdir ~/gcc-2.7.1
	cd ~/gcc-2.7.1
	zcat ~/bounds-checking-2.7.1-x.y-binary-cpu-mf-system.tgz | tar xvf -

Compile programs with bounds checking
-------------------------------------

Once you've got the program compiled, use the `-fbounds-checking' flag
to add bounds checking to your programs. Eg.

	~/gcc-2.7.1/xgcc -B~/gcc-2.7.1/ -fbounds-checking -c file1.c -o file1.o
	~/gcc-2.7.1/xgcc -B~/gcc-2.7.1/ -fbounds-checking file1.o -o program

Notice that:
  (1) I've assumed you have compiled/installed GCC in `~/gcc-2.7.1'.
  (2) You need to pass the `-B' option to tell GCC which directory you're
      using. Note that the directory needs a trailing `/'.

For Makefiles, you could add/change the following rules:

	GCC_HOME = $(HOME)/gcc-2.7.1
	CC = $(GCC_HOME)/xgcc
	CFLAGS = -B$(GCC_HOME)/ -fbounds-checking -g -Wall ..etc..

The first place to look for information is the GCC info page. The relevant
files are:

	~/gcc-2.7.1/gcc.info
	~/gcc-2.7.1/gcc.info-*

You will need `emacs', `tkinfo' or similar, to read them.

There is an old manual in PostScript form in the file:

	~/gcc-2.7.1/bounds/report/bcrep2.ps.gz

and the source for this (in M$-Word 6 format - yes, I know):

	~/gcc-2.7.1/bounds/report/bcrep2.doc.gz

Special cases for bounds checking
---------------------------------

Although bounds checking ought to be automatic, if you use one of the
following constructs, you may need to change your program:

    .   signal handlers
        threads
                Read the user manual. For signal handlers, you will need to
                move the signal handlers into unchecked code. There are
                hooks in the checking library for threads.
    .   <stdarg.h>
        <varargs.h>
                The `va_arg' macro does not work. You need to include
                `gcc-2.7.1/bounds/run-includes/fix-args.h' after including
                <stdarg.h> or <varargs.h>.
    .   Using `-2' as a pointer.
                You can't use `-2' as a special pointer representation (because
                I use it). To fix this, either change your code to use, say,
                -1, or change the definition of ILLEGAL in `bounds/lib/
                bounds-lib.h'.

Read the user manual for more details.

Bug reports
-----------

There are a few known bugs: read about them in

	~/gcc-2.7.1/bounds/BUGS

Please send bug reports & fixes to

	rwmj@doc.ic.ac.uk

Related documents
-----------------

http://www-ala.doc.ic.ac.uk/~phjk/BoundsChecking.html
http://www-dse.doc.ic.ac.uk/~rj3/bounds-checking.html

Platforms
---------

We have tested the program on these platforms:

        Linux 1.2.13
        SunOS 4.1.3 (mark@sgcs.com)
        ESIX SVR 4.0.4 on a 486 machine (herman@htbrug.hobby.nl)
        OSF 2.0 on DEC Alpha (tuppa@iue.tuwien.ac.at)
        Solaris (what version?)
        HPUX (what version?)

The extensions ought to run on any platform that supports GCC.
