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.

BASIC ERROR-HANDLING REQUIREMENTS

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.

THROWING EXCEPTIONS

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.

ADDING C++ EXCEPTIONS TO YOUR CODE

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.

USING C++

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" {
#endif

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

#ifdef __cplusplus
}
#endif

CREATING A TOP-LEVEL EXCEPTION HANDLER IN MAIN

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 {
      CreateFile(paramPtr);
      WriteFile(paramPtr);
   }
   catch (...) {
      ReportError("\pSerious error occurred.")
      // XCMDs do not have to use ExitToShell. 
   }
   SetA4(oldA4);
}

DEFINING TRY BLOCKS

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.

DEFINING CATCH BLOCKS

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. 
   HandleError(errString);
}
catch (OSErr theErr) {
   Str255 errString;
   ConvertErrToString(theErr, errString);
   ReportError(errString);
   throw (theErr);   // Rethrow to handle error.
}
// Forces the application to quit after the message.
catch (...) {
   SignalPStr_("\pUntyped error occurred in prefs.") 
   ExitToShell();
}
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.

MOVING DEEPER -- HANDLING EXCEPTIONS IN THE CALL CHAIN

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)
{
   CreateResFile(fileName); 
   // Could also use the Metrowerks ThrowIfResError_ macro.
   err = ResError();
   if (err <> noErr)
      throw (err);
   // Continue with execution.
   ...
}

// Call the function.
MakeThisFile()
{
   ...
   try {
      MakeMyResFile(thisFile);
   }
   catch (OSErr theErr) {
      if (theErr == dupFNErr) {
         // Do something; file already exists.
         ...
      }
      else 
         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.

EXCEPTIONS AND DEBUGGING WITH THE METROWERKS MACROS

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.*

SETTING GLOBAL VARIABLES FOR DEBUGGING

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.

THE THROW MACROS

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)
   ThrowIfOSErr_(err); 

THE SIGNAL MACROS

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).

STRESS REDUCTION WITH EXCEPTION HANDLING

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!


    RELATED READING

    • 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

Kill the Plumber World guide - How to ou...
You already know how to hop around like Mario, but do you know how to defeat him? Those are your marching orders in Kill the Plumber, and it's not always as easy as it looks. Here are some tips to get you started. This is not a seasoned platform... | Read more »
Planar Conquest (Games)
Planar Conquest 1.0 Device: iOS Universal Category: Games Price: $12.99, Version: 1.0 (iTunes) Description: IMPORTANT: Planar Conquest is compatible only with iPad 3 & newer devices, iPhone 5 & newer. It’s NOT compatible with... | Read more »
We talk to Cheetah Mobile about its plan...
Piano Tiles 2 is a fast-paced rhythm action high score chaser out now on iOS and Android. You have to tap a series of black tiles that appear on the screen in time to the music, being careful not to accidentally hit anywhere else. Do that and it's... | Read more »
Ultimate Briefcase guide - How to dodge...
Ultimate Briefcase is a simple but tricky game that’s highly dependent on how fast you can react. We can still offer you a few tips and tricks on how to survive though. Guess what? That’s exactly what we’re going to do now. Take it easy [Read more... | Read more »
SoundPrism Link Edition (Music)
SoundPrism Link Edition 1.0 Device: iOS Universal Category: Music Price: $4.99, Version: 1.0 (iTunes) Description: ***Introductory price for a the first few days after launch - if you're reading this, get it while it's fresh out of... | Read more »
Pre-register now for hack and slasher An...
Fincon, which won Facebook's Studio to Watch award in 2015, has announced that pre-registration is now open for the massive 3.0 update for its award-winning hack and slasher Angel Stone. Angel Stone is a post-apocalyptic action RPG in which the... | Read more »
Google has named Piano Tiles 2 as its Be...
Google has named Piano Tiles 2, which launched back in August last year, as its Best Game of 2015. If you're yet to play it, now's a good time to do so. It's a sequel to the hugely successful viral hit Piano Tiles (Don't Tap the White Tile) but... | Read more »
Sago Mini Trucks and Diggers (Education...
Sago Mini Trucks and Diggers 1.0 Device: iOS Universal Category: Education Price: $2.99, Version: 1.0 (iTunes) Description: Drive a dump truck with Rosie the hamster! Pile dirt high and dig deep in the ground with diggers, cranes and... | Read more »
Day One 2 Journal + Notes (Lifestyle)
Day One 2 Journal + Notes 2.0 Device: iOS Universal Category: Lifestyle Price: $4.99, Version: 2.0 (iTunes) Description: **New Release Sale—50% off for a Limited Time!** Capture life as you live it. From once-in-a-lifetime events to... | Read more »
Pull My Tongue (Games)
Pull My Tongue 1.0 Device: iOS Universal Category: Games Price: $.99, Version: 1.0 (iTunes) Description: Meet Greg. A hungry little chameleon that loves popcorn! Help feed Greg by pulling his tongue through a series of fun puzzles... | Read more »

Price Scanner via MacPrices.net

Watch Super Bowl 50 Live On Your iPad For Fre...
Watch Super Bowl 50 LIVE on the CBS Sports app for iPad and Apple TV. Get the app and then tune in Sunday, February 7, 2016 at 6:30 PM ET to catch every moment of the big game. The CBS Sports app is... Read more
Two-thirds Of All Smart Watches Shipped In 20...
Apple dominated the smart watch market in 2015, accounting for over 12 million units and two-thirds of all shipments according to Canalys market research analysts’ estimates. Samsung returned to... Read more
12-inch 1.2GHz Retina MacBooks on sale for up...
B&H Photo has 12″ 1.2GHz Retina MacBooks on sale for $180 off MSRP. Shipping is free, and B&H charges NY tax only: - 12″ 1.2GHz Gray Retina MacBook: $1499 $100 off MSRP - 12″ 1.2GHz Silver... Read more
12-inch 1.1GHz Gray Retina MacBook on sale fo...
B&H Photo has the 12″ 1.1GHz Gray Retina MacBook on sale for $1199 including free shipping plus NY sales tax only. Their price is $100 off MSRP, and it’s the lowest price available for this model... Read more
Apple now offering full line of Certified Ref...
Apple now has a full line of Certified Refurbished 2015 21″ & 27″ iMacs available for up to $350 off MSRP. Apple’s one-year warranty is standard, and shipping is free. The following models are... Read more
Free GUI Speedometer – The Ultimate Digital D...
Miami, Florida based RMKapps has announced the official release of GUI Speedometer 1.0, their digital dashboard display developed for iOS devices. GUI Speedometer allows users to track their precise... Read more
FutureCalc: Ergonomic iOS Calculator App For...
London, United Kingdom based Independent software developer and entrepreneur, Hovik Melikyan has announced the release and immediate availability of FutureCalc 1.0, his new ergonomic calculator app... Read more
Save up to $600 with Apple refurbished Mac Pr...
Apple has Certified Refurbished Mac Pros available for up to $600 off the cost of new models. An Apple one-year warranty is included with each Mac Pro, and shipping is free. The following... Read more
Apple’s ‘Next Big Thing’ Drought And Mature M...
Apple’s first fiscal quarter 2016 financial results yielded both good news and bad news. In the positive column, Apple made another boatload of money, reporting record quarterly revenue of $75.9... Read more
Lifeproof NUUD For iPhone 6S, iPhone 6S Plus...
LifeProof NUUD was designed to defy more than the elements. It defies logic itself by combining legendary four-proof protection and screenless technology to survive mountaintop missions and seaside... Read more

Jobs Board

Restaurant Manager - Apple Gilroy Inc./Apple...
…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
Simply Mac *Apple* Specialist- Service Repa...
Simply Mac is the largest premier retailer of Apple products in the nation. In order to support our growing customer base, we are currently looking for a driven Read more
*Apple* IOS / OS X Level 3 Support Analyst -...
Needed: Apple Support Analyst (OS X / IOS); 50k-60k/yr +…Horizon Technology Partners has an immediate opening for an Apple IOS / OS X LEVEL 3 Support Analyst. Your Read more
*Apple* - Software QA Manager - Apple Inc. (...
Changing the world is all in a day's work at Apple . If you love innovation, here's your chance to make a career of it. You'll work hard. But the job comes with more than Read more
Restaurant Manager - Apple Gilroy Inc./Apple...
…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.