This article presents a set of macros which supports exception handling in ANSI/ISO C. Programs using these macros need no special pre-processing; the Standard C pre-processor pass will suffice.

Exceptions can be defined, thrown, and caught with a uniform block-oriented syntax. Top-level handlers can be installed for exceptions that would otherwise not be caught. The package also includes a callback facility which can restore user-defined data structures when exceptions are thrown.

if (idx >= length) {
   fprintf(stderr, "Out of range!");
   exit(1);
}

if ((ptr = malloc(size)) == NULL)
   return 1;
if ((f = fopen(name, "r")) == NULL)
   return 2;
return 0; /* OK */

rename(name, another_name);
f = fopen(name, "w");

A radically different approach to the problem is a technique called exception handling. An exception is an unusual condition which is not handled explicitly in the code executed during normal operation. Instead, the control will jump to an alternative block of code if an exception is detected. Often, the exception is an error condition, but it can also represent some other type of event.

In C, exception handling can be implemented with the setjmp/longjmp facility. However, direct calls to these functions make the code unnecessarily hard to read. In addition, it will be very difficult to make error handling routines in different modules cooperate unless they adhere to some conventions for using setjmp/longjmp. One solution is to encapsulate these calls in macros with clear syntax and well-defined semantics.

In the system described here, code segments where exceptions might occur are encapsulated in try-blocks. If an exception is detected in such a block, we may throw an exception by executing a throw statement. The control will then be transferred immediately to an alternative piece of code, called the unwind-block, which has been associated with the try-block in a TRY macro call:

TRY (try-block, unwind-block);

TRY(
{
   /* Try something */
   if (failure)
      THROW(exc); /* throw-point */
   /* On success, continue here */
},
{
 /* On failure, continue here */
}
);

CATCH (exception, catch-form);

TRY(
{
   p = malloc(1024);
   if (p == NULL)
      THROW(out_of_memory);
},
{
   CATCH(out_of_memory,
   {
     /* Handle memory allocation failures here */
   });
});

TRY(
{
   /* try-block */
},
{
   CATCH(out_of_memory, { ... });
   CATCH(read_error,    { ... });
   CATCH(write_error,   { ... });
});

The application code must obviously be able to distinguish between different exceptions, and in this system addresses of variables are used for that purpose. The main advantage is that a user can easily define his own exceptions just by creating new local or global variables. The linker guarantees that all (simultaneously existing) exception variables are assigned unique addresses in the program.

Any type of exception variable can be used for identifying exceptions. Actually, any lvalue with an address will do. Since the THROW and CATCH macros only care about addresses, the space occupied by an exception variable can be used for transferring information from the throw-point to the unwind-block. The variable will typically contain a status code (integer) or an error message (string), which has been set before the throw.

struct {
   struct {
      int read_failed;
      int write_failed;
   } io;
   struct {
      int out_of_memory;
      int already_free;
   } memory;
} foo;

TRY(
{
   p = malloc(256);

   if (!p)
      THROW(foo.memory.
   out_of_memory);
   f(p);
},
{
   CATCH(foo.io, { ... });
   CATCH(foo,    { ... });
}
);

void f(void) 
{
   TRY (
   {
      return g();
   },
   {
      unwind ();
   });
}

Sometimes it is convenient to catch some exception, process it, and then execute a more general unwind-code. The break statement can be used in CATCH statements for that purpose. In the following example, the allocated buffer will be released for all exceptions thrown.

void *volatile buf = NULL;

TRY(
{
   if ((buf = malloc(256)) == NULL)
      THROW(out_of_memory);

if (fscanf(stdin, "%d %255s", &i, buf) != 2)
   THROW (illegal_syntax);
},
{
CATCH(illegal_syntax,
{
   fprintf(stderr, "Syntax err!");
   break;
});

if (buf) free(buf);
});

int h(void *e, void *e_type, void *data);

EXC_INSTALL_HANDLER(dom, h, data);

When a handler is called, the e parameter will contain the actual exception thrown. It is guaranteed to belong to the domain specified as the first argument of EXC_INSTALL_HANDLER. The data parameter will contain the void pointer given as the third argument of EXC_INSTALL_HANDLER. The pointer value is private to the handler and will not be interpreted by the exception system. The e_type parameter specifies the exception variable type, which will be discussed below.

If several handlers are installed, the latest installed one (with a matching domain tag) will be called first. If the handler ends with return, the exception is assumed to be completely processed, and the exception system will call exit with the status value returned from the handler. In contrast, if a handler executes THROW, the next handler (i.e., a handler installed before the current one) will be called if its domain tag matches the pending exception. Thus, handlers are always called in reverse installation order. A handler can also be installed with the special domain symbol exc_any, which will match any exception.

When should handlers be installed? Suppose that a library defines and throws some exceptions, and that all its exception variables are strings containing error messages created at the throw-point. Such a library would typically install (in its initialization function) a handler to print out these messages.

Still, there are situations where the type is completely unknown, for example when a handler installed for exc_any is called. In such cases, it can be useful to associate the exception variable with a type tag at the throw-point with THROW_TYPED. This macro works like THROW but takes an extra type variable. Actually, exception types are also identified by variable addresses, just like the exceptions whose types they represent:

int my_type;
MyData err;
THROW_TYPED (err, my_type);

if (EXC_IN_DOMAIN(e_type, my_type))
{
MyData my_data = *(MyData *) e;

...
}

void cb(excCallbackTag tag, void *cb_data,
       void **try_data);

exc_install_callback(tags, cb, cb_data);

• excBeginCallback. The callback function will be invoked whenever a new TRY is entered.
• excEndCallback. The callback will be called if the try-block completes normally, i.e., not with a throw.
• excThrowCallback. The callback will be called if an exception is thrown. The call is made at the throw-point, before the stack has been unwound.
• excRecoverCallback. The callback is invoked when the program has recovered from an exception.

cb_data is a void pointer associated with the callback function. The pointer is specified when the callback is installed and is not altered or interpreted by the exception system. The try_data parameter specifies the address of a void pointer variable, which is automatically allocated by the exception library for each callback whenever a new try-block is entered. The contents of this void pointer is private to the callback and can be used for any purpose. It is usually set in the callback function when tag is excBeginCallback read when tag is excEndCallback or excThrowCallback. (However, try_data will be a null pointer in excEndCallback and excThrowCallback calls if the callback function was not installed when the corresponding TRY was entered.)