Bounds Checking Patches for GCC 2.7.2
-------------------------------------

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

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.2-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.2-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.2'. Patch the tree as follows:

	cd ~				# BC unpacks into `gcc-2.7.2/'
	zcat bounds-checking-2.7.2-x.y.tgz | tar xvf -
	cd gcc-2.7.2
	patch -p1 < bounds-checking.diff
	make distclean			# Clean up source tree.

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

	cd ~/gcc-2.7.2
	./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
--------------------------------

The binary distribution now unpacks in the directory `gcc-2.7.2/'. You
should do:

	zcat bounds-checking-2.7.2-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.2/xgcc -B~/gcc-2.7.2/ -fbounds-checking -c file1.c -o file1.o
	~/gcc-2.7.2/xgcc -B~/gcc-2.7.2/ -fbounds-checking file1.o -o program

Notice that:
  (1) I've assumed you have compiled/installed GCC in `~/gcc-2.7.2'.
  (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.2
	CC = $(GCC_HOME)/xgcc
	CFLAGS = -B$(GCC_HOME)/ -fbounds-checking -g -Wall ..etc..

Looking for information
-----------------------

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

	~/gcc-2.7.2/gcc.info
	~/gcc-2.7.2/gcc.info-*

You will need `emacs', `tkinfo' or similar, to read them. Go to `Bounds
Checking' node.

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

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

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

	~/gcc-2.7.2/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.
    .   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 gcc.info file for more details.

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

There are a few known bugs: read about them in

	~/gcc-2.7.2/bounds/BUGS

Please send bug reports & fixes to

	rwmj@doc.ic.ac.uk

Frequently asked questions
--------------------------

These are questions I've answered more than a hundred times already ...

1.	No, it doesn't work with C++. But do you feel like giving up ~1-2
	months of your time to implement it for me? If so, write soon.

2.	The patches break G77 (GNU FORTRAN compiler). Solution: Copy
	cp/bounds.c to f/bounds.c and add this file to the list of files
	to be compiled in f/Makefile.in. This doesn't add bounds checking
	to G77, incidentally (:-<) it just lets you compile G77 with GCC and
	bounds checking.

3.	When will the patches be integrated into GCC? I have no answer to
	this. One day soon, when I feel that the software has been widely
	tested and the bugs have been all but eliminated, I will apply to
	have this happen. However, the GCC maintainers may have other ideas,
	in which case the answer will be `never'.

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

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

Platforms
---------

See the file MACHINES in the distribution to see what machines GCC/BC has been
ported to. It ought to work on just about any machine that GCC supports.
