Mac OS X Server 1.x: About Exception Handling on Mac OS X Server

Note: This article pertains to Mac OS X Server versions 1.x, which were released prior to May 2001.

Application Errors

Certain types of application errors typically cause Yellow Box applications to exit abruptly. A new user default, NSExceptionHandlingMask, has been provided to control this behavior (for AppKit-based applications only) for three of the most common classes of such errors:

• uncaught NSExceptions;
• system-level exceptions (such as invalid memory accesses); and
• Objective C runtime errors (such as messages sent to freed objects).

Setting NSExceptionHandlingMask causes the application to optionally (a) print a descriptive log and a stack trace to the console when such an error occurs, or (b) handle the error in such a way as to prevent the resulting abrupt termination, or both. The mask is constructed by summing values corresponding to the types of errors to be logged or handled: 1 for logging uncaught NSExceptions, 2 for handling them; 4 for logging system-level exceptions, 8 for handling them; 16 for logging runtime errors, 32 for handling them. Thus

defaults write NSGlobalDomain NSExceptionHandlingMask 63

will cause all of these types of errors to be both logged and handled for all applications.

System-level exceptions and runtime errors are handled by converting them into NSExceptions. NSExceptions generated in this manner will contain a stack trace in their userInfo under the key "NSStackTraceKey". Uncaught NSExceptions are handled by terminating the thread in which they occur (NSExceptions in an application's main thread are caught by NSApplication's top-level handlers).

In addition to the use of the NSExceptionHandlingMask user default to control this behavior for AppKit-based applications, the same functionality can also be accessed programmatically from both application and non-application Yellow Box executables by linking against the ExceptionHandling framework and calling

[[NSExceptionHandler defaultExceptionHandler] setExceptionHandlingMask:aMask]

See the ExceptionHandling.framework header files for more details on the NSExceptionHandler API.

Debugging Aids

For debugging purposes, it is also possible to use the same mechanism to report on NSExceptions that would otherwise be caught. The additional values that may be added to NSExceptionHandlingMask for this purpose are 64 for logging exceptions that would be caught by the top-level exception handlers in NSApplication, 128 for handling them, 256 for logging exceptions that would be caught at lower levels, and 512 for handling them. In these cases, handling an exception means nothing more than adding a stack trace to its userInfo under the key "NSStackTraceKey". Note that caught exceptions should be logged or handled only for debugging, not under normal circumstances, because doing so may generate large amounts of output, or alter the normal behavior of applications.

For further debugging purposes, it is possible to change the handling behavior for any condition handled by NSExceptionHandler so that the application will instead be halted to wait for a debugger to be attached. This is controlled by the NSExceptionHangingMask user default, constructed by summing values corresponding to the conditions under which the application should hang: 1 for uncaught NSExceptions, 2 for system-level exceptions, 4 for runtime errors, 8 for top-level caught NSExceptions, and 16 for other caught NSExceptions.

In addition, a tool called atos has been provided to convert numeric stack traces into symbolic form. See the atos(1) man page for details.