Untitled

Bounds Checking

The C part of the GNU compiler now supports full fine-grained pointer checking at runtime. This work was originally done by Richard W.M. Jones `rjones@orchestream.com', and has been extended by the work of many other kind contributors.¹

The runtime checking library, test kit and various tools can be found in the bounds/ subdirectory.

The brief manual here is a distillation of the original paper that appeared at the same time as the original patches to GCC. The paper contains more details about the inner workings of bounds checking GCC. The paper can be found in PostScript format in bounds/report/bcrep2.ps.gz.

Compiling with checks: How to compile your programs with bounds checks on at runtime.
Incompatibilities with checking: You can't use setjmp/longjmp, and threads and signal handlers need special attention.
Unchecked code and libraries: You can freely mix unchecked source files and libraries with your checked program.
Debugging with GDB: You may debug bounds checked programs with GDB and there are special breakpoints for this purpose.
Environment at runtime: Customizing the runtime environment by passing options in GCC_BOUNDS_OPTS.
Managing the heap: How bounds checking uses the heap at runtime.
Unchecked objects: How unchecked objects work.
Miscellaneous features: Other features that might be of interest.
Checking 2D array indices: Notes about 2D array indices.
What errors are caught: What errors are caught and what errors are missed?
Performance: How fast (or slow) can you expect bounds checked programs to go?
Stubborn bugs: Special ``features'' you may need to know about.
Using G77 with bounds checking: A small patch you have to make to get a smooth compile with G77.

Node:Compiling with checks, Next:Incompatibilities with checking, Up:Bounds Checking

Compiling with checks

To compile all or part of your program with bounds checking, simply add the -fbounds-checking flag when compiling and linking. In the simplest instance, you might do:

gcc -fbounds-checking program.c -o program

Or, linking several checked files together:

gcc -fbounds-checking -c file1.c -o file1.o
gcc -fbounds-checking -c file2.c -o file2.o
gcc -fbounds-checking -c file3.c -o file3.o
gcc -fbounds-checking file1.o file2.o file3.o -o program

If your program uses a Makefile, you will probably only need to add the -fbounds-checking flag to CFLAGS, and remake the program from scratch.

Node:Incompatibilities with checking, Next:Unchecked code and libraries, Previous:Compiling with checks, Up:Bounds Checking

Incompatibilities with checking

Programs that use setjmp and longjmp.
Bounds checking is unfortunately incompatible with setjmp/longjmp. This is regrettable, but the problem is quite fundamental and it is unlikely that these functions will ever be permissable.
Using signal handlers.
If possible, move signal handlers to a separate source file and set checking off in that file. If this is not possible, then you will need to edit bounds/lib/mutex.h which provides mutual exclusion to vital internal structures in the checking library. Normally this mutual exclusion is turned off, for reasons of efficiency.
Using threads.
You may use threads with bounds checking. If more than one thread could ever run with bounds checking, you will need to provide mutual exclusion as with signal handlers above. Edit the file bounds/lib/mutex.h and add whatever code is necessary to give mutual exclusion.
Checking C++ programs.
Every so often, someone mails me to ask why their C++ program isn't checked when they do g++ -fbounds-checking. At the moment, the bounds checking changes are specific to the C front end, so you can't use them with the other GCC front ends (eg. C++, FORTRAN, Modula-2). There is no reason why bounds checking couldn't be added to the C++ front end. It would take perhaps one or two months to do. It is highly unlikely that I will ever do this, but if a keen beta-tester wants it enough, I may be willing to help them. In the meantime, it is possible to translate C++ programs to C and check them, but line number and other debugging information may get scrambled in the process.

Node:Unchecked code and libraries, Next:Debugging with GDB, Previous:Incompatibilities with checking, Up:Bounds Checking

Unchecked code and libraries

You can normally freely mix unchecked and checked code. This is why you don't need to make any changes to your C or X11 libraries when you install GCC with bounds checking. The checking library will detect code compiled with and without checking automagically, and let the two run together. You can mix unchecked object files with checked ones for the same reason. Always pass the -fbounds-checking flag to the link stage.

gcc -fbounds-checking -c file1.c -o file1.o
gcc -c unchecked.c -o unchecked.o
gcc -fbounds-checking file1.o unchecked.o -o program

The checking library will usually only know about variables that are declared in checked code, and about memory allocated with malloc. So if a variable is declared in unchecked.c above, then references to it will not be checked, even when these references occur in checked code.

Say that file unchecked.c contains the following code:

int a[10];

int *get_ptr_to_a () { return a; }

and file file1.c contains:

extern int *get_ptr_to_a ();

main ()
{
  int *ptr_to_a = get_ptr_to_a ();
  int i;

  for (i = 0; i < 20; ++i) ptr_to_a[i] = 0;
}

The references to ptr_to_a will not be checked. You can resolve this by adding a, either by hand, or semi-automatically. See Unchecked objects.

If you place extern int a[10]; anywhere in file1.c, bounds checking GCC will also be able to find and check the array references properly.

If you include bounds/run-includes/unchecked.h, you get facilities to turn bounds checking on and off over short stretches of code and within single expressions and statements. Even when bounds checking is switched off, you may still use these features. The macros are silently ignored if bounds checking is off, or if the compiler is not GCC.

BOUNDS_CHECKING_OFF ... BOUNDS_CHECKING_ON
Turn off bounds checking over a section of code. For instance:
```
/* This code is checked ... */
BOUNDS_CHECKING_OFF;
/* This code is unchecked ... */
BOUNDS_CHECKING_ON;
/* This code is checked again ... */
```
The unchecked code should not try to return from a function, or jump over the BOUNDS_CHECKING_ON statement with goto, else checking will be switched off for the rest of the program!
BOUNDS_CHECKING_OFF_DURING
Switch off checking in a single statement. For instance:
```
BOUNDS_CHECKING_OFF_DURING (p += 5);
```
The statement should not (obviously) be goto, return, ...
BOUNDS_CHECKING_OFF_IN_EXPR
Switch off checking while a single expression is being evaluated. For instance:
```
p = BOUNDS_CHECKING_OFF_IN_EXPR (a + 5);
```

Node:Debugging with GDB, Next:Environment at runtime, Previous:Unchecked code and libraries, Up:Bounds Checking

Debugging with GDB

If you have GDB (or another debugger) on your system, you will be able to debug bounds checked programs easily and efficiently. To help you catch bounds errors before the program aborts (which sometimes causes the program's stack to disappear), place a breakpoint at __bounds_breakpoint. The checking library always calls this breakpoint before aborting. If the -never-fatal flag has been supplied See Environment at runtime, you will need to place this breakpoint, since the program does not abort when it hits a bounds error.

Node:Environment at runtime, Next:Managing the heap, Previous:Debugging with GDB, Up:Bounds Checking

Environment at runtime

You can customize the way a bounds-checked program runs by passing options to it in the environment variable `GCC_BOUNDS_OPTS'. For instance, suppose you don't want the banner message that appears when bounds checked programs start up. With sh or ksh, you might type:

% GCC_BOUNDS_OPTS='-no-message' program

With csh:

% setenv GCC_BOUNDS_OPTS '-no-message'; program

You can put any combination of the following flags in GCC_BOUNDS_OPTS. Place spaces or tabs between each flag.

-no-message: Don't print the introductory message.
-no-statistics: Don't print library call statistics with the program quits.
-?, -help: Print this list of options, then quit the program before it starts.
-reuse-heap (*)
-reuse-age=<age>
-no-reuse-heap: See the discussion of heap memory, See Managing the heap.
-warn-unchecked-statics
-no-warn-unchecked-statics (*)
-warn-unchecked-stack
-no-warn-unchecked-stack (*): See the discussion of unchecked objects, See Unchecked objects.
-warn-free-null (*)
-no-warn-free-null: Give a warning if free (0) is called. Note that this may be correct in ANSI C, and some libraries, notably X11, do it quite often.
-warn-misc-strings (*)
-no-warn-misc-strings: Miscellaneous warnings with str* and mem* functions, such as trying to call memcpy with size = 0.
-warn-illegal
-no-warn-illegal (*): Warn when ILLEGAL pointers are generated. These patches, provided by Don Lewis <gdonl@gv.ssi1.com>, help to track down ILLEGAL pointer errors when they happen.
-warn-unaligned (*)
-no-warn-unaligned: Warn when a pointer is used in an unaligned manner, for instance reading integer data as chars. This warning is turned on by default, but may be disabled, since some programs do this quite harmlessly. These patches were suggested by Stuart Kemp and Eberhard Mattes.
-warn-all: Turn on all of the warnings above.
-array-index-check (*)
-no-array-index-check: Check 2D array indices correctly. This is turned on by default. This will only check arrays with size > 1. This is done to avoid problems with structure hack definintions. See Checking 2D array indices.
-never-fatal: Normally the library will call abort() after it detects the first bounds error. If this flag is given, the library attempts to proceed. The first error may generate more errors itself afterwards, so only the first error is guaranteed to be correct.
-print-calls
-no-print-calls (*): Print calls to the checking library. This option is only useful if you want to debug bounds checking GCC itself.
-print-heap
-print-heap-long
-no-print-heap (*): Print the contents of the heap at program end. This is useful to find memory leaks in your program. -print-heap shows the total leaked memory for each malloc call, while -print-heap-long shows each leaked allocation in detail.

Items marked with a `(*)' are the default.

Node:Managing the heap, Next:Unchecked objects, Previous:Environment at runtime, Up:Bounds Checking

Managing the heap

The bounds checking library includes a customized version of the GNU malloc library. Calls to malloc, free, realloc, calloc, cfree, valloc and memalign are checked. You will get a bounds error if you try to:

Free a pointer that has not been allocated in the proper way, or free a pointer twice.
Reallocate a pointer that has not been allocated, or has been freed.
Use a pointer to freed memory, or to memory that has been moved by realloc.
Free or reallocate static memory.

There are several strategies for tracking stale memory pointers. Ideally, we would like to never reuse VM after the programmer has freed it, so that we will always be able to detect a stale pointer, no matter how long the program runs before using it. If you wish this behaviour, then pass the -no-reuse-heap option in `GCC_BOUNDS_OPTS' See Environment at runtime.²

In practice, we found this technique to be wasteful, so the default is to reuse heap memory immediately. However, in order to provide some protection against stale pointers, you may pass the -reuse-age=<age> option to the library. This will add freed blocks to a queue of pending blocks. You must call free <age> times before the block is actually reused.

Notice that the most common error is:

free_list (list *p)
{
  for (; p != NULL; p = p->next)
    free (p);
}

The default flags, -reuse-heap -reuse-age=0, will catch this error.

Node:Unchecked objects, Next:Miscellaneous features, Previous:Managing the heap, Up:Bounds Checking

Unchecked objects

Variables declared in files that are not compiled with -fbounds-checking are not normally known about by the checking library. Pointers that point to these variables are not checked, even where the operations on these pointers happen within checked code. To be sure that your program is running without any errors, you should turn on warnings about unchecked operations by giving the -warn-unchecked-statics and/or -warn-unchecked-stack flags at runtime. See Environment at runtime.

To avoid these warnings, and check all operations, you should take steps to add these objects to the tree used by the checking library. There are three approaches:

Declare the object as extern somewhere in checked code. Make sure that the size of the object appears in the expression, ie. extern int a[10];, not extern int a[];.

Add the object by hand by calling __bounds_note_constructed_object. This function is declared:

void __bounds_note_constructed_object (ptr, size, align, filename, line, name);
  void *ptr;      /* Pointer to the object. */
  size_t size;    /* Size of the object (bytes). */
  size_t align;   /* Pass 1 here. */
  char *filename; /* Filename where declared (for debugging). */
  int line;       /* Line number. */
  char *name;     /* Name of the object. */

Add all the objects from a single object file, or a library automagically, using the grab-statics tool in bounds/tools. There is a README file in that directory that will tell you more.

Node:Miscellaneous features, Next:Checking 2D array indices, Previous:Unchecked objects, Up:Bounds Checking

Miscellaneous features

Detecting when a source file is being compiled with bounds checking.
When GCC compiles a file with the -fbounds-checking flag, it defines __BOUNDS_CHECKING_ON in the preprocessor. In addition, the variable __bounds_checking_on is set to 1 when bounds checking is on in the program as a whole, and set to 0 when it is not. The variable is actually located in libgcc.a, so it is always present (unless you aren't using GCC).
Notice the subtle difference between these two methods. Say a program consists of source files file1.c and file2.c. If the program is compiled with
```
gcc -fbounds-checking -c file1.c
gcc -c file2.c
gcc -fbounds-checking file1.o file2.o -o program
```
then file1.c will be compiled with __BOUNDS_CHECKING_ON defined. In file2.c this will not be defined. Both files will be able to declare extern int __bounds_checking_on; and the variable will be read as 1 by both.
If the same files are compiled without bounds checking, then __BOUNDS_CHECKING_ON will not be defined. Both files will be able to declare extern int __bounds_checking_on; and will read the variable as 0.
If the same files are compiled with another C compiler, then variable __bounds_checking_on will not exist. So all references to this variable should be defended by #ifdef __GNUC__ ... #endif.

Node:Checking 2D array indices, Next:What errors are caught, Previous:Miscellaneous features, Up:Bounds Checking

Checking 2D array indices

2D arrays (and, indeed, n-D arrays with n >= 2) are checked as you might expect. We consider such arrays to be flattened before checking. For instance a mathematical 3x3-matrix A might be defined as:

double A[3][3];

When -no-array-index-check is active we consider such a array as flattened. Bounds checking will then consider this to be a flat array with 9 elements. So, it is perfectly sound to write A[1][4], since 1*3+4 == 7, and 0 <= 7 < 9. Similarly, A[0][8] and A[2][-1] will not generate bounds errors. (Interestingly, though, errors in the first index will be caught -- this is to do with a subtlety in the way bounds checking works).

When -array-index-check is present every dimension of the array is checked separatly. This is the default. This flag is only used for arrays with size > 1. For arrays with size of 1 or 0 the flattened model is used. This allows the following code to work correctly.

struct _string_t
{
  int len;
  char str[1];
};

Node:What errors are caught, Next:Performance, Previous:Checking 2D array indices, Up:Bounds Checking

What errors are caught

A lot of people tell me that they have Purify, and bounds checking GCC seems unnecessary, since it seems to duplicate Purify but more slowly. Well, there are important reasons why bounds checking GCC is better than Purify, and if you rely on Purify alone, you will certainly miss bugs in your program.

This is what bounds checking GCC will find, which Purify won't:

Bounds of stack and static variables
Try compiling:
```
main ()
{
  int a[10], b[100], i;

  for (i = 0; i < 100; ++i)
    a[i] = 0;
}
```
Purify will only detect these sorts of errors reliably if a is allocated with malloc.

Large offsets from memory allocated with malloc

Bugs such as the following one will not be found reliably by Purify, since it only puts a certain amount of blank padding between malloc'd memory.

struct large_type {
  int data[5000];
};

main ()
{
  char *m1;
  struct large_type *m2;
  int i;

  m1 = (char *) malloc (20000);
  m2 = (struct large_type *) malloc (sizeof (struct large_type) * 5);

  for (i = 4; i >= -2; --i) /* note: error when i == -1 */
    m2[i].data[0] = 0;
}

This is what Purify will find, which bounds checking GCC won't:

Using a variable or memory before it is initialized
Bounds checking GCC can't currently check this, but it may well be added in a future version. GCC itself will pick up simple instances of this if you pass the -Winitialized flag (without -fbounds-checking), but cannot check use of malloc'd memory.

There is a freeware program which emulates Purify available from Tristan Gingold <gingold@amoco.saclay.cea.fr>. It only runs under Linux. Purify only works on Sun SPARCstations and HP-PA machines, and, of course, costs lots of cash.

Node:Performance, Next:Stubborn bugs, Previous:What errors are caught, Up:Bounds Checking

Performance

This page is under construction.

Node:Stubborn bugs, Next:Using G77 with bounds checking, Previous:Performance, Up:Bounds Checking

Stubborn bugs

The very latest list of bugs can be found in bounds/BUGS. This is a list of some of the most stubborn bugs, some of which have been around since the first version. Please send bug reports and (even better) bug fixes to `rjones@orchestream.com' or `Haj.Ten.Brugge@net.HCC.nl'.

Padding missed out between aggregates and 32-bit objects on the stack.
Bounds checking GCC usually inserts bytes of padding between adjacent stack objects. This dead area between objects helps the checking library to detect the difference between a pointer to the last byte + 1 of one object and a pointer to the first byte of the next object. For some reason, this padding is omitted occasionally when a 32-bit object (eg. int, pointer) follows an aggregate (eg. array). But not always.
The bug used to happen under Linux, but at some point in the past it seems to have fixed itself. The bug still appears under Solaris. You can demonstrate the bug by compiling Tcl/Tk on Solaris. The checking library will report at run time that a reference has been made to the byte following the end of the first object. When you look at the code, you will see that it is in fact referring to the next object (ie. the 32-bit integer).
Update (16/10/95): I fixed some stuff in assign_stack_local and assign_outer_stack_local (thanks to Don Lewis <gdonl@gv.ssi1.com>) but I haven't been able to verify that this bug has gone for sure.

Node:Using G77 with bounds checking, Previous:Stubborn bugs, Up:Bounds Checking

Using G77 with bounds checking

Bounds checking patches break the current G77 patches. You can get round this very easily. Copy cp/bounds.c into the f/ subdirectory. Alter f/Makefile.in so that it compiles bounds.c along with the other G77 object files.

Notice that this doesn't add bounds checking to FORTRAN (:-<). Just lets you compile it.

Footnotes

See the file bounds/CONTRIBUTORS for a full list of the people who gave their effort for free to make all this possible.
In a future version of bounds checking GCC, we will be able to unmap this memory. Thus the operating system will be able to reuse physical memory, whilest virtual memory addresses remain unused.