TweetFollow Us on Twitter

March 96 - Using C++ Exceptions in C

Using C++ Exceptions in C

Avi Rappoport

Exception handling in C++ offers many advantages over error handling in C. Using the techniques outlined here, you can implement C++ exceptions in your C code without a lot of effort. The payback is streamlined debugging that can result in more error-free code. When your program encounters errors, it jumps to the appropriate error-handling section, rather than dealing with the error locally. This simplifies your design and helps you concentrate on the normal flow of control. Centralized error handling also makes it easier to improve your reporting and feedback mechanisms incrementally.

I wrote a few little XCMDs in C and after the fifteenth crash of the day, I decided that I'd better add some error handling. So I looked at Dartmouth XCMDs, but I wasn't impressed. Each check for an error meant another indentation in the code, and I was worried about disposing of handles correctly as I passed errors up the call chain. Since I'd been looking at a lot of C++ lately, I wondered whether I couldn't use part of the C++ exception-handling mechanism to avoid problems in my code. It worked pretty well, so I thought I'd share my results.

For part of my solution, I used some Metrowerks macros. Metrowerks has graciously allowed these helpful exception and debugging source, header, and resource files to be included on this issue's CD, so you can use them without purchasing its CodeWarrior CD. The files contain macros that provide convenient tools for implementing exceptions and debugging signals, as well as an alert resource that can provide information during debugging.

Although I've used C++ exception handling in my C code with great results, I'd like to offer you one word of caution before you use them. Realize that C++ is not strictly an extension of C; as a result, in some cases it's possible that the program may not behave as you think it should.


All programs must respond to system and subroutine failures somehow. For example, many Macintosh Toolbox routines return a variable of type OSErr, while others require that you call Toolbox routines (such as MemError and ResError) to retrieve the error. If you ignore system and subroutine failures, your program is practically guaranteed to crash.

Good error handling allows you to cope with many kinds of problems. Your checks can trigger other code that deals with the problem (for example, by freeing memory). During debugging, error checking should notify you that something has gone wrong. And since you can't, unfortunately, catch all the bugs during testing, you must also set up an error-reporting mechanism to notify your users when something has gone wrong. In the worst case, your error handling should at least ensure that your program exits gracefully, without losing or corrupting user data.


The American National Standards Institute (ANSI) has defined a mechanism for C++ compilers that allows code to "throw" exceptions. When the compiler encounters a throw statement, it jumps to the nearest catch statement. (The "nearest" catch statement is the one associated with the current try statement, whether it's in the current routine or farther up the call chain.) The catch statement can deal with the error, pass it up the call chain, or both. A throw statement should appear only within a try or catch statement or in code called from within a try statement. Listing 1 shows these basic components.

Listing 1. Throwing exceptions

OSErr theErr = noErr;

// Try block.
try {
   // Do something.
   // If error, throw an exception.
   if (theErr != noErr)
      throw (theErr);
// Catch blocks.
catch (OSErr theErr) {
   // Do something with the error.
catch (...) {
   // Catch anything else.
As shown in Listing 1, exceptions are dealt with in catch blocks, which take an appropriate action depending on the error. For serious errors, this means cleaning up and terminating the program. For less serious errors, the catch block could continue without making a fuss, or make changes based on the error and again call the routine that threw the error; sometimes you might want to throw a more generic error, which is caught and interpreted in a higher-level catch block. I also recommend using the Metrowerks signal macros (described later) within your catch blocks to help you locate errors during debugging.
    The three dots in catch (...) are actually in the code; the other such dots that appear in these listings are ellipses representing code that isn't shown.*
When carefully designed, C++ exception handling in your program can deal with problems at an appropriate level. As you may already have guessed, this feature is both powerful and dangerous. The advantage is that you don't have to mess around with returning errors for every routine or indenting deeply. However, if you allocate memory, you must be careful to dispose of it at the right time or it will cause a leak.


To add C++ exceptions to your code, you must do the following:
  • Force the use of the C++ compiler.
  • Create a top-level exception handler in your main routine.
  • Define try blocks and catch blocks, and call throw at appropriate times.
  • Add the C++ library (CPlusPlus.lib, CPlusPlusA4.lib, or MWCRuntime.Lib) to your project.
The Metrowerks macros that you'll see in the code that follows make implementing exception handling much easier than it would be otherwise. I'll talk about them later.


To use C++ exceptions, you have to force the use of the C++ compiler. In Metrowerks CodeWarrior, the easiest way is to select the Activate C++ Compiler checkbox in the C/C++ Language panel. You should also make sure that the Enable C++ Exceptions checkbox is selected, because it enables throwing exceptions rather than direct destruction (one of those weird C++ things). An alternative way to invoke the compiler is to change the extension on your source code files to ".cp" or by changing the Target panel preferences; however, the checkbox method is the easiest.

C++ is stricter about automatic parameter conversion than C, so selecting the MPW Pointer Type Rules checkbox in the C/C++ Language panel avoids a bunch of errors (it forces the compiler to allow some implicit char* casts). But you'll get errors for other parameters and return values, so you have to clean them up as indicated by the compiler. For example, the following is an error message returned by a C++ compiler:

HC2RTF.c line 224  textLen = strlen(textString);
Error   : cannot convert
'unsigned char *' to
'char *'
To fix this problem, you can change the code to
textLen = strlen((char *) textString)
The CodeWarrior C++ compiler puts special C++ information into function names (this is called name mangling). C doesn't do this, so header files for C functions should be surrounded by #extern "C" statements to tell the compiler not to mangle these names (see Listing 2). The Macintosh Toolbox header files take care of this already.

Listing 2. Preventing name mangling

#ifdef __cplusplus
extern "C" {

long   FindBreak(char* buffer, short len);
// More declarations here

#ifdef __cplusplus


In your main loop or function, you should specify the top-level exception handler. This should catch serious errors, report them, and exit gracefully. Listing 3 shows the simplest possible exception handler (which you'll understand better as you read on).

Listing 3. Simple top-level exception handler

pascal void main(XCmdPtr paramPtr)
   long   oldA4 = SetCurrentA4();

   try {
   catch (...) {
      ReportError("\pSerious error occurred.")
      // XCMDs do not have to use ExitToShell. 


When you use a try statement, it tells the compiler that the following code might have exceptions thrown in it. All functions that throw exceptions must be within a try block, either in the current function or in a calling function. It's pretty easy to set up try blocks before catch blocks. This is good, because you do have to do it: any throws that aren't caught will automatically abort the program.


You should have catch blocks for each error type. So, for example, you might define catch (OSErr theErr), catch (errStruct errRecord), and catch (Str255 theErr). You should also have a generic catch, catch (...), which doesn't have any parameters, to catch exceptions of all other types. Although it's better to use typed catches that handle specific errors, always add at least one generic catch and have it signal an error with an alert or break to the debugger. This will help you catch exception mistakes during your debugging and testing phase. Listing 4 shows examples of these types of catch blocks.

Listing 4. Specific and generic catch blocks

catch (StringPtr errString) {
   // If HandleError throws, it will be caught above this catch. 
catch (OSErr theErr) {
   Str255 errString;
   ConvertErrToString(theErr, errString);
   throw (theErr);   // Rethrow to handle error.
// Forces the application to quit after the message.
catch (...) {
   SignalPStr_("\pUntyped error occurred in prefs.") 
The compiler automatically routes the error to the appropriate catch statement, depending on the parameter passed to the throw statement. In Listing 4, both the StringPtr and OSErr types are caught specifically, after which they're reported. The OSErr catch rethrows the error as well. Any other types of errors are caught by the generic catch, which calls a signal macro to display a message and then exits the program.

You can, and often should, continue after catching an error. For example, after a disk full error, you should allow the user to choose a different volume. Note that the program will continue after the catch block, rather than in the location where the exception was thrown.


Many of your low-level routines may call the Macintosh Toolbox or otherwise interact with the Mac OS. They should throw an exception if there's an error, as shown in Listing 5.

Listing 5. Throwing exceptions for Macintosh Toolbox errors

void MakeMyResFile(Str32 fileName)
   // Could also use the Metrowerks ThrowIfResError_ macro.
   err = ResError();
   if (err <> noErr)
      throw (err);
   // Continue with execution.

// Call the function.
   try {
   catch (OSErr theErr) {
      if (theErr == dupFNErr) {
         // Do something; file already exists.
         throw (theErr);   // Rethrow the error.
   }   // End catch statement.
So where do you catch these exceptions? Remember, they percolate up the call chain until they find a catch statement, so you don't have to take care of them in the immediate calling function (unless you've allocated memory or done other things that need undoing). When you catch them, you can, and sometimes should, throw the error again. You can either report errors in mid-level routines or rethrow them up to a higher-level error reporting mechanism.

In addition to these catch statements, be sure to add a catch statement in circumstances where you need to do any of the following:

  • Dispose of handles and otherwise deallocate memory.
  • Shut down something you started in the try block, such as opening a file.
  • Change the error thrown.
For your own functions, you should throw errors in situations that can cause serious problems or crash the machine. For instance, if you're providing a function that accesses a variable-length array that contains 16 members and the caller asks for the 17th member, you can throw a range error. There's no hard-and-fast rule about when to put the error checking into a function and when to require it before calling -- it depends on the situation. For example, if you're calling a function inside a tight graphics loop only and you want speed, you can probably check the parameters sufficiently in the calling function. However, if you have a utility routine that's called from several sections of your code, adding error checking will help you remember its requirements, such as parameters, memory, and other system states, to avoid problems later on.

Handling exceptions in libraries is tricky because you don't know much about the calling program. Think carefully about what you should report to the user and what you should simply return to calling functions.

As your programs become more sophisticated, you can start working around certain errors -- for example, by using temporary memory when the application's heap is full. You'll also need to design interactive error reporting, allowing your users to take action (such as unlocking a locked disk) when they can. Then your application can continue properly.


The Metrowerks PowerPlant UDebugging and UException files, included on this issue's CD, provide convenient tools for throwing common exceptions and alerting you during debugging. To use them, put the folder in your project folder, add the sources and the "PP DebugAlerts.rsrc" resource file to your project, and include the headers in your source files.

The UException.h file includes macros that automate common exception conditions. The UException.cp file includes an abort function. The UDebugging.h file defines some macros that make locating problems easier by allowing you to specify a signal, a debugging string displayed when the macro is invoked.

    If your project includes an ANSI library you don't need to add UException.cp. The abort function will conflict.*


You need to set the global variables gDebugThrow and gDebugSignal in UDebugging.h to specify the debugging actions for throws and signals. By default, they're set to do nothing at all. Other options include displaying a dialog, dropping into the source-level debugger, or dropping into the low-level debugger. To activate the macros, be sure to define Debug_Signal in your precompiled header or UDebugging.h.

The following are the global variable options:

  • debugAction_Nothing -- Do nothing.
  • debugAction_Alert -- Display an alert box with an exception code (described later), filename, and line number where the throw or signal was made. For this to work, you must include the file "PP DebugAlerts.rsrc" in your project.
  • debugAction_SourceDebugger -- Break into the source-level debugger. For the Metrowerks source-level debugger, execution will stop with the arrow pointing to the line containing the throw statement. The exception code isn't displayed. You can check the display of variable values in the source-level debugger for that information. (I've tested this with the Metrowerks debugger only.) If you aren't running under the source-level debugger, debugAction_SourceDebugger will break into the low-level debugger on PowerPC processor-based machines, but might crash on 680x0 systems.
  • debugAction_LowLevelDebugger -- Break into MacsBug and display the exception code as a string. In MacsBug, the console will display two lines:
User Break at routine + offset
exception code 
  • Note that if you don't have a low-level debugger installed, your program will crash with an unimplemented trap error if it tries to break into the low-level debugger.


UException.h defines several useful macros that automatically perform tests and throw exceptions if a test failed. It also defines a type, ExceptionCode (a long), and two standard exceptions, err_AssertFailed ('asrt') and err_NilPointer ('nilP'), which are treated as type ExceptionCode. Here are the throw macros:
  • ThrowIf_(test) -- Throws an exception if test is true, where test is a Boolean or the result of a Boolean condition. The exception code will be err_AssertFailed.
  • ThrowIfNot_(test) -- Throws an exception if test is false. The exception code will be err_AssertFailed.
  • ThrowIfOSErr_(err) -- Throws an exception if err isn't equal to noErr.
  • ThrowOSErr_ (err), FailOSErr_ (err) -- Throws an exception with err as the exception code.
  • ThrowIfNULL_(ptr), ThrowIfNil_(ptr), FailNil_(ptr) -- If ptr is NULL (or nil), throws an exception with err_NilPointer as the exception code.
  • ThrowIfMemError_() -- Calls the Toolbox routine MemError and throws an exception if it returns a result that's not equal to noErr; the MemError return becomes the exception code.
  • ThrowIfMemFail_(p) -- Throws an exception if p (a pointer or a handle) is nil. The MemError routine is used to check the success or failure of the last Memory Manager call. If MemError returns a result that's not equal to noErr, the exception code is set to the return value of the MemError call. If MemError returns noErr, the exception code is set to memFullErr, a constant defined by Apple.
  • ThrowIfResError_() -- Calls the Toolbox routine ResError and throws an exception if it returns a result that's not equal to noErr; the result becomes the exception code. ResError is used to check the success or failure of the last Resource Manager call.
  • ThrowIfResFail_(h) -- Throws an exception if h (a handle to a resource) is nil. If ResError returns a result that's not equal to noErr, the exception code is set to that result. If ResError returns noErr, the exception code is set to resNotFound, a constant defined by Apple.
You can use all of the macros within if-else clauses, as they're designed to be self-contained. For example:
if (err != fnfErr)


UDebugging.h defines macros for raising signals, also known as asserts. These will stop the execution of the program and report errors. You can use them to check for nil pointers, out-of-range offsets, excess length, division by zero, and other problems. If you remove the definition of Debug_Signal, the entire set of macros is converted to white space and takes no runtime overhead whatsoever.

The macros are defined to check gDebugSignal for the action to take on execution, as described previously.

The following are the signal macros:

  • SignalPStr_(pstr) takes a Pascal string argument. The string can be a literal Pascal string (in double quotes beginning with \p) or a StringPtr variable (and its variants, such as Str255).
  • SignalCStr_(cstr) takes a literal C string argument. The string must be a literal (text within double quotes) and can't be a char*. Because the underlying Toolbox routines take Pascal strings, the SignalPStr_ macro is more efficient.
  • SignalIf_(test), SignalIfNot_(test) each take a Boolean condition as an argument and raise a signal depending on whether the condition is true or false.
  • Assert_(test) is a synonym for SignalIfNot_(test).


C++ exceptions and these Metrowerks macros make error handling reasonably easy to add to most programs. With a little thought, you can design a clean structure for dealing with Mac OS errors and internal errors -- a structure that's easily extensible to new code. You can avoid stress during testing by adding signal macro calls for common errors throughout your code. They're much easier to debug than system crashes. And yes, thank you, my XCMDs are much better now!


    • For a more in-depth examination of exceptions in C++, consult the article "Try C++ Exception Handling" by Kent Sandvik (MacTech Magazine, October 1995). For another view of C exceptions, see "Living in an Exceptional World" by Sean Parent in develop Issue 11.
    • For information on the return values of Macintosh Toolbox routines and the error codes, see the Inside Macintosh series, Macintosh Programmer's Toolbox Assistant, and THINK Reference. You can also look at the header file Errors.h.

    Because C has no objects, when you read these publications, you can ignore all discussions of object throwing, exception objects, construction, and destruction.

AVI RAPPOPORT has degrees in medieval studies and library/information studies, so she feels well qualified to work in the Macintosh software industry. In her job as user advocate and publications coordinator at Metrowerks, she spent her time documenting PowerPlant, making conference calls, and frantically trying to check CodeWarrior CDs before they were burned. Avi now works at StarNine as product manager for messaging products. She lives in Berkeley, California, with her Mac/Web scripter husband and their four-year-old son -- all BMUG members.*

Thanks to Greg Dow, Pete Gontier, Tom Lippincott, and Jon Wätte for their C++ wizardry and personal patience, and to Pete and Tom for reviewing this article.*


Community Search:
MacTech Search:

Software Updates via MacUpdate

The beginner's guide to Warbits
Warbits is a turn-based strategy that's clearly inspired by Nintendo's Advance Wars series. Since turn-based strategy games can be kind of tricky to dive into, see below for a few tips to help you in the beginning. Positioning is crucial [Read... | Read more »
How to upgrade your character in Spellsp...
So you’ve mastered the basics of Spellspire. By which I mean you’ve realised it’s all about spelling things in a spire. What next? Well you’re going to need to figure out how to toughen up your character. It’s all well and good being able to spell... | Read more »
5 mash-ups we'd love to...
If there's one thing that has proved, it's that the addictive gameplay of can be transplanted onto basically anything and it will still be good fun. It wouldn't be surprising if we saw other developers jumping on the bandwagon,... | Read more »
How to navigate the terrain in Sky Charm...
Sky Charms is a whimsical match-'em up adventure that uses creative level design to really ramp up the difficulty. [Read more] | Read more »
Victorious Knight (Games)
Victorious Knight 1.3 Device: iOS Universal Category: Games Price: $1.99, Version: 1.3 (iTunes) Description: New challenges awaits you! Experience fresh RPG experience with a unique combat mechanic, packed with high quality 3D... | Read more »
Agent Gumball - Roguelike Spy Game (Gam...
Agent Gumball - Roguelike Spy Game 1.0 Device: iOS Universal Category: Games Price: $2.99, Version: 1.0 (iTunes) Description: Someone’s been spying on Gumball. What the what?! Two can play at that game! GO UNDERCOVERSneak past enemy... | Read more »
Runaway Toad (Games)
Runaway Toad 1.0 Device: iOS Universal Category: Games Price: $2.99, Version: 1.0 (iTunes) Description: It ain’t easy bein’ green! Tap, hold, and swipe to help Toad hop to safety in this gorgeous new action game from the creators of... | Read more »
PsyCard (Games)
PsyCard 1.0 Device: iOS Universal Category: Games Price: $1.99, Version: 1.0 (iTunes) Description: From the makers och Card City Nights, Progress To 100 and Ittle Dew PSYCARD is a minesweeper-like game set in a cozy cyberpunk... | Read more »
Sago Mini Robot Party (Education)
Sago Mini Robot Party 1.0 Device: iOS Universal Category: Education Price: $2.99, Version: 1.0 (iTunes) Description: -- Children's Technology Review Editor's Choice -- | Read more »
How to get a high score in every level o...
Sky Charms is an adorable match three puzzler that provides a decent challenge thanks to its creative level design. It regularly presents something new, forcing you to think on your feet. [Read more] | Read more »

Price Scanner via

Apple restocks Certified Refurbished Mac mini...
Apple has restocked Certified Refurbished 2014 Mac minis, with models available starting at $419. Apple’s one-year warranty is included with each mini, and shipping is free: - 1.4GHz Mac mini: $419 $... Read more
15-inch 2.2GHz Retina MacBook Pro on sale for... has the 15″ 2.2GHz Retina MacBook Pro on sale for $1699.99 including free shipping. Their price is $300 off MSRP, and it’s the lowest price available for this model from any reseller (and... Read more
Apple Beats Microsoft at Own Game; Amazon Pri...
First quarter seasonality combined with an overall disinterested customer base led to an annual decline of 14.7% in worldwide tablet shipments during the first quarter of 2016 (1Q16). Worldwide... Read more
Tablets Had Worst Quarter Since 2012, says St...
The global tablet market began 2016 just as 2015 left off, down. Tablet shipments fell 10% to 46.5 million units during the Q1 2016, according to the new “Preliminary Global Tablet Shipments and... Read more
Clearance 13-inch MacBook Airs, Apple refurbi...
Apple recently dropped prices on certified refurbished 2015 13″ MacBook Airs with 4GB of RAM with models now available starting at $759. An Apple one-year warranty is included with each MacBook, and... Read more
Clearance 12-inch Retina MacBooks, Apple refu...
Apple has dropped prices on Certified Refurbished 2015 12″ Retina MacBooks with models now available starting at $929. Apple will include a standard one-year warranty with each MacBook, and shipping... Read more
Aleratec Releases Mac Software Upgrade for 1...
California based Aleratec Inc., designer, developer and manufacturer of Portable Device Management (PDM) charge/sync products for mobile devices and professional-grade duplicators for hard disk... Read more
Sale! Amazon offers 27-inch iMac, 13-inch 2.9...
Amazon has the 27″ 3.2GHz 5K iMac and the 13″ 3.9GHz Retina MacBook Pro on sale for $300 off MSRP, each including free shipping, for a limited time: - 27″ 3.2GHz/1TB HD 5K iMac (model MK462LL/A): $... Read more
Apple refurbished 13-inch Retina MacBook Pros...
Apple has Certified Refurbished 13″ Retina MacBook Pros available for up to $270 off the cost of new models. An Apple one-year warranty is included with each model, and shipping is free: - 13″ 2.7GHz... Read more
13-inch 2.7GHz/128GB Retina MacBook Pro on sa...
Take $200 off MSRP on the price of a new 13″ 2.7GHz/128GB Retina MacBook Pro (model MF839LL/A) at Amazon. Shipping is free: - 13″ 2.7GHz/128GB Retina MacBook Pro: $1099.99 $200 off MSRP Act now if... Read more

Jobs Board

Restaurant Manager (Neighborhood Captain) - A...
…in every aspect of daily operation. WHY YOU'LL LIKE IT: You'll be the Big Apple . You'll solve problems. You'll get to show your ability to handle the stress and Read more
Automotive Sales Consultant - Apple Ford Linc...
…you. The best candidates are smart, technologically savvy and are customer focused. Apple Ford Lincoln Apple Valley is different, because: $30,000 annual salary Read more
*Apple* Retail - Multiple Positions - Apple,...
Job Description: Sales Specialist - Retail Customer Service and Sales Transform Apple Store visitors into loyal Apple customers. When customers enter the store, Read more
*Apple* Solutions Consultant - Apple (United...
# Apple Solutions Consultant Job Number: 48260200 Phoenix, Arizona, United States Posted: Apr. 22, 2016 Weekly Hours: 40.00 **Job Summary** As an Apple Solutions Read more
Restaurant Manager (Neighborhood Captain) - A...
…in every aspect of daily operation. WHY YOU'LL LIKE IT: You'll be the Big Apple . You'll solve problems. You'll get to show your ability to handle the stress and Read more
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.