Introduction

• lessons learned about the language features themselves apply to all versions of standard C++, whatever the platform, whereas details of the implementation are specific to both the vendor and the platform.
• knowing how it works is not necessary to using it
• the details are very sketchily documented and not guaranteed by Microsoft to remain unchanged

• I can satisfy my 'how do they do that?' curiousity
• I can understand the flow of control when trying to debug application problems
• I can perhaps provide some platform specific value-added services.

	void testStackTrace()
	{
	    ExceptionStackTrace helper;

	    try
	    {
	        doSomethingWhichMightThrow();
	    }
	    catch ( std::exception & ex )
	    {
	        std::cerr << "Exception occurred: " << ex.what() << std::endl;
	        helper.printStackTrace( std::cerr );
	    }
	}

Exception occurred: A sample error...
  Frame       Code address
  0x0012FE70  0x7C57E592 RaiseException+0x55
  0x0012FEB0  0x7C359AED CxxThrowException+0x34
  0x0012FF10  0x004013CA throwIt+0x4a at teststacktrace.cpp(32)
  0x0012FF18  0x004013E8 doSomethingWhichMightThrow+0x8 at teststacktrace.cpp(37)
  0x0012FF58  0x0040142A testStackTrace+0x3a at teststacktrace.cpp(45)
  0x0012FF60  0x004014A8 main+0x8 at teststacktrace.cpp(57)
  0x0012FFC0  0x00404E87 mainCRTStartup+0x143 at crtexe.c(398)
  0x0012FFF0  0x7C581AF6 OpenEventA+0x63d

Processing the Stack Trace

So here is a function prototype for a simple stack trace routine implemented using the functionality of DbgHelp.dll:

	void SimpleSymbolEngine::StackTrace( CONTEXT *pContextRecord, std::ostream & os );

A context record can be obtained in a variety of ways. As it is simply a snapshot of the thread state it could be built up manually using inline assembler to populate the various fields from CPU registers - or more easily by using the GetThreadContext call. The operating system also uses them in various places when managing thread state and finally they also crop up in exception handling.

The main reason to write the 'ExceptionHelper' class is to obtain the context record of the thread state when the exception occurred. We can then use this key piece of data to extract the stack trace. Let's look at Microsoft's implementation of try, throw and catch in Win32 C++ to see how it lets us build something to extract this information.

Structured exception handling

The definitive article about Win32 structured exception handling is by Matt Peitrek [2] and I refer interested readers there. However, his article focuses on the Microsoft extensions to support SEH: _try, _except and _finally and less on the language native concepts embodied in try, throw, etc. Other articles, such as [3], focus on what is happening at the assembler level which is great for the minority of programmers who understand assembler but not for the rest.

There is a relatively natural fit between the SEH exception model and the 'try ... catch' exception model in programming languages such as C++ so it is not too surprising that Microsoft decided to use this operating system level structured exception handling to provide the basis for their C++ exception handling code. However other implementors of C++ on the Win32 platform have not necessarily followed the same pattern.

Windows provides a portable exception architecture which recognises two main type of exceptions: 'system' exceptions such as an access violation or an integer divide by zero, which are also known as 'asynchronous' exceptions, and 'user' exceptions generated by a call to RaiseException(), which are also known as 'synchronous' exceptions. Each thread contains a linked list of exception handlers and when an exception occurs information about the exception and a context record for the thread are passed to each exception handler in the chain in turn for possible processing. There are several things each handler can do; the commonest cases are:

• return 'keep looking' (and the next exception handler will be called)
• unwind the thread context back to a known state and execute a failure path (in C++, a 'catch' block).

Each handler has a signature like this:

DWORD exceptionHandler( EXCEPTION_RECORD *pException, EXCEPTION_REGISTRATION_RECORD *pRegistrationRecord, CONTEXT *pContext );

• pException contains information about the exception being processed, such as the exception code and the fault address.
• pRegistrationRecord points to the current node in the list of exception handlers
• pContext contains the processor-specific thread state when the exception occurred

What makes this exception style 'structured' is that the chain of exception handlers exists in the thread's own stack. In a typically block-structured programming language each call to a function, method or procedure pushes a new activation frame onto the stack; this frame contains the current arguments, any local variables and the exception handler for this function (if any). Additionally, the algorithm which passes the exception along the chain of handlers naturally moves from the most recently called function up the stack to the top most function.

In the Win32 world the 'ESP' register contains the current stack pointer, by convention the current frame pointer is usually held in the 'EBP' register and the 'FS' selector register holds the base of the thread information block (TIB) which holds, among other things, the head of the exception chain.

To try and make this clearer here is a schematic representation of the bottom of the stack when function 'A' has called function 'B' which in turn has called function 'C'. Functions A and C have an SEH handler, but function B doesn't.

Inside the each stack frame the function arguments are above the frame register (and appear in assembler as [EBP + offset]) and local variables are below the frame register (and appear in assembler as [EBP - offset]). In practice things are more complicated than this - particularly when the optimiser gets involved - and the frame register EBP can get used for other purposes. To reduce the complexity of this article I'm not going to worry about optimised code.

We need insert our own exception helper object into the chain of exception registration records so we can extract the context record for the thrown exception.

MSVC exception handling

	void thrower()
        {
		SomeClass anObject; // ** 5 **
		throw std::runtime_error( "An error" ); // ** 2 **
	}

	void catcher()
	{	// ** 1 **
		std::string functionName( "catcher" );
		try
		{
			thrower();
		}
		catch ( std::exception & ex )	// ** 3 **
		{
			std::cerr << functionName << ": " << ex.what() << std::endl;	
		}
	}	// ** 4 **

2) 'Throw' is implemented by calling RaiseException with a special exception code 0xe06d7363 (the low bits spell 'msc' in ascii). Other fields in the exception record are set up to hold the address and run-time type of the thrown object - in this case a std::runtime_error object.

3) The catch code is actually implemented by the exception handler. If the exception being handled has the special exception code value then the run-time type information is extracted and compared to the type of the argument in the catch statement. If a match is found (or a conversion is possible) then the exception chain is unwound and the body of the catch is entered, after which the execution will continue directly after the try ... catch block. If a match is not found the exception handler returns the 'keep looking' value and the new handler in the chain will be tried.

4) On function exit the exception handler for catcher is removed from the chain.

5) There's another place that SEH code is needed of course - the destructor for 'anObject' must be called during the unwind back to the 'catch' statement. So there is actually yet another exception handler registered for 'thrower' too, to deal with ensuring that anObject gets deleted. This one never tries to handle the exception but simply ensures local variables are destructed during the unwind.

One key thing about the way MSVC exception handling works is that it involves making extra calls down the stack. At point (2) the C++ runtime calls RaiseException, which snapshots the exception and thread state and then it in turn calls the code to work along the exception chain calling exception handlers. At point (3) when the exception handler for 'catcher' gets control it is a long way down the stack. The exception chain is unwound by yet another call, this time to RtlUnwind. This function throws another exception along the exception chain with a special flag value 'EXCEPTION_UNWINDING' set, giving each exception handler in turn a chance to do tidying up before it is removed from the exception chain. After returning from RtlUnwind the body of the catch statement is then called. When the catch body completes control returns back to the C++ runtime which completes tidying up the stack pointer, deletes the exception object and then resumes execution at the next instruction after the catch block.

So how does the catch block make use of the local variable 'functionName' if it is so far down the stack when it gets control?

What the C++ runtime does is to use the extended exception registration record (passed to the handler as the second argument) to recover the value of the frame pointer EBP. Having reset the frame pointer the code in the catch body can make use of local variables and function arguments without difficulty. It is does not affect the function that the stack pointer is not simply a few bytes below the frame pointer but several hundred bytes below it.

The upshot is that, when the catch body is executed, the complete stack down to the location of the 'throw' is still available in memory. The raw stack pointer will only be reset when the body of the stack completes, and before this point the call stack will not be touched. So if we can obtain the address of the context record that was passed into each exception handler as the third argument, the pointer will still be valid inside the body of the catch.

Looking back to the way the chain of exception handlers is processed we can see that if we can hook our code into the exception chain just before the compiler written exception handler we can extract information from the context record and then use that information inside the catch handler to allow us print a stack trace. Let's look at how we can do this.

Adding to the exception chain

	/** Typedef for the exception handler function prototype */
	typedef DWORD (fnExceptionHandler)( EXCEPTION_RECORD *pException, struct _EXCEPTION_REGISTRATION_RECORD *pRegistrationRecord, CONTEXT *pContext );

	/** Definition of 'raw' WinNt exception registration record - this ought to be in WinNt.h */
	struct _EXCEPTION_REGISTRATION_RECORD
	{
	    struct _EXCEPTION_REGISTRATION_RECORD *PrevExceptionRegistrationRecord; // Chain to previous record
	    fnExceptionHandler *ExceptionHandler; // Handler function being registered
	};

Firstly, the code which walks the exception chain requires (on some but not all versions of Windows) that the nodes in the chain are registered in strict address order. Fortunately the compiler always puts local variables below the exception registration record so by using a local variable for our exception helper we should always be able to insert it into the chain before the compiler generated exception registration record.

Secondly, I want to register the exception handler in a constructor. This function too has a compiler-generated exception handler. I must ensure that the handler is registered in the chain above the record for the constructor or my exception handler will be unregistered when the constructor completes! Additionally I want the code to work properly should there be two or more exception helper objects in a single function, and it is not in general possible to fix the offsets in the stack frame assigned by the compiler for local variables.

Lastly, as part of the security improvements included with Visual Studio .NET 2003 and Windows Server 2003/Windows XP service pack 2, the exception handling function to be called must be marked with a special attribute ('SAFESEH') at link time so it will appear in the "Safe Exception Handler Table" in the load configuration record. Failure to do this results in a security exception occurring at runtime which usually terminates the process. This check has been added to Windows to prevent security exploits that use buffer overrun in order to replace the exception handler address on the stack with a pointer to injected code. The SAFESEH attribute can only be granted by assembler code so it is therefore necessary, when using Visual Studio .NET 2003, to make use of a very simple piece of assembler code to add this attribute to the exception handling function.

Note: the assembler 'ml.exe' provided with the first Beta edition of Visual Studio 2005 access violates when using /safeseh [4] and that from 2003 must be used.

One mechanism I've found that provides good ease of use under the above constraints is to create a common base class for my own exception handlers. This class contains a static exception handling function which can be marked, once and for all, with the SAFESEH attribute. This common handler then makes a virtual call into the derived class for the specific action required for exception handling.

	class ExceptionHelperBase : public _EXCEPTION_REGISTRATION_RECORD
	{
	public:
	    /** Construct helper object */
	    ExceptionHelperBase();

	    /** Make safe to extend */
	    virtual ~ExceptionHelperBase() {}

	    /** Allow subclass to hook exception */
	    virtual void onException( EXCEPTION_RECORD *pException, CONTEXT *pContext ) = 0;

	private:
	    // Disable copy and assign
	    ExceptionHelperBase( ExceptionHelperBase const & );
	    ExceptionHelperBase& operator=( ExceptionHelperBase const & );

            // The one and only exception handler function
	    static fnExceptionHandler exceptionHandler;
	};

	DWORD ExceptionHelperBase::exceptionHandler( EXCEPTION_RECORD *pException, struct _EXCEPTION_REGISTRATION_RECORD *pRegistrationRecord, CONTEXT *pContext )
	{
	    ExceptionHelperBase &self = static_cast( *pRegistrationRecord );
	    self.onException( pException, pContext );
            return ExceptionContinueSearch;
	}

	    template 
	    class AutoRegister : public RegistrationRecord
	    {
	    public:
	        /** Auto-register an exception record for 'RegistrationRecord' */
	        AutoRegister()
	        : RegistrationRecord()
	        {
	            registerHandler( this );
	        }

	        /** Unregister and destroy an exception record */
	        ~AutoRegister()
	        {
	            unregisterHandler( this );
	        }
	    };

Processing the exception

	class ExceptionHelperImpl1 : public ExceptionHelperBase
	{
	    /** Print the address of the exception records */
	    virtual void onException( EXCEPTION_RECORD *pException, CONTEXT *pContext )
	    {
	       printf( "pException: %p (code: %p, flags: %x), pContext: %p\n", pException, pException->ExceptionCode, pException->ExceptionFlags, pContext );
	    }
	};

	typedef AutoRegister< ExceptionHelperImpl1 > ExceptionHelper1;

Sample code:

	int main()
	{
	    ExceptionHelper1 helper;

	    try
	    {
	        printf( "About to throw\n" );
	        throw std::runtime_error( "basic exception" );
	    }
	    catch ( std::exception & /*ex*/ )
	    {
	        printf( "In catch handler\n" );
	    }
            return 0;
	}

	About to throw
	pException: 0012FBA0 (code: E06D7363, flags: 1), pContext: 0012FBC0
	pException: 0012FBA0 (code: E06D7363, flags: 3), pContext: 0012F670
	In catch handler

We now have everything we need for the basic version of the code to print a stack trace:

	class ExceptionStackTraceImpl : public ExceptionHelperBase
	{
	public:
	    ExceptionStackTraceImpl() : pSavedContext(0) {}

	    /** Use the saved pointer to print the stack trace */
	    void printStackTrace( std::ostream & os ) const
	    {
	        if ( pSavedContext != 0 )
	            SimpleSymbolEngine::instance().StackTrace( pSavedContext, os );
	    }

	private:
	    /** Capture the thread context when the initial exception occurred */
	    virtual void onException( EXCEPTION_RECORD *pException, CONTEXT *pContext )
	    {
	       if ( ( pException->ExceptionFlags & EXCEPTION_UNWINDING ) == 0 )
	       {
	           pSavedContext = pContext;
	       }
	    }

	    PCONTEXT pSavedContext; // context record from the last exception
	};

	typedef AutoRegister< ExceptionStackTraceImpl > ExceptionStackTrace;

Interaction with normal SEH

Visual Studio 2005 Beta 1 handles non-C++ SEH exceptions in a catch( ... ) only when the compiler flag /EHa is set, which is a great improvement and gives maximum flexibility.

Whether or not /EHa is specified we can use ExceptionHelper to extract information about the OS exception. Microsoft provide some other ways to achieve a similar end, __try/__except and _set_se_translator, but they are not total solutions. Also not all compler vendors provide such extensions and the ExceptionHelper code could still be used to extract information about the exception.

For example I modified ExceptionHelper1 class for gcc on win32 (a couple of minor changes were required for a clean compile). Since gcc does not seem to use SEH for C++ exception handling ExceptionHelper1 did not capture information for such exceptions but it did do so for Win32 exceptions, such as access violations. For a "proof of concept" I changed the exception handler to throw a std::runtime exception rather than printing the exception information and was successful in mapping an SEH exception into a C++ exception, thus allowing additional tidyup to be performed before the program exited.

Conclusion

What is the main strength and weakness of this approach?

On the positive side it enables better diagnostic information to be produced at runtime for MSVC on win32. This can significantly reduce the cost of finding bugs, since enough information might be gathered in the field to identify the root cause. Without this extra information it might be necessary to try and reproduce the problem under a debugger, with potential difficultly of getting the right execution environment to enure the problem does in fact appear.

The main weakness is that the code is platform specific and relies on undocumented behaviour of the compiler. Other compilers under Win32 do not use the SEH mechanism to handle C++ exceptions so this code is useless should your code need to be portable to them. The implementation of the exception mechanism even under 64bit windows is not the same as for 32 bit windows, so the technique described here will not work unchanged (if at all) in that environment even for Microsoft compilers.

The decision depends on the relative balance between these two items. However, having isolated the logic into a single class 'ExceptionStackTrace' it can be conditionally compiled to a do-nothing implementation on other platforms, or if may even be possible to re-implement the logic for another platform.

Updates

I have made this change to the code in the zip file.

Klaus Triendl also pointed out that the exception handler should have a 4th parameter `void* DispatcherContext'. This is correct, but the final parameter can be safely ignored if it is not used, as the function uses the C calling convention and so the caller is responsible for clearing up the stack.

Note on multi-threaded programs.

The simple stack walking code above may fail in unpredictable ways if an exception occurs in more than one thread at once. The Microsoft documentation for the functions in the DbgHelp library states: 
"All DbgHelp functions, such as this one, are single threaded. Therefore, calls from more than one thread to this function will likely result in unexpected behavior or memory corruption. To avoid this, you must synchronize all concurrent calls from more than one thread to this function."

Hence if you wish to debug multi-threaded programs you will need to add some explicit synchronisation to the access to the DbgHelp library. My apologies to Jonathan Lepolt, who was affected by this problem, for not making this clear in the original article.

References