Structured exception handling (SEH) is a Microsoft extension to C and C++ to handle certain exceptional code situations, such as hardware faults, gracefully. Although Windows and Microsoft C++ support SEH, we recommend that you use ISO-standard C++ exception handling in C++ code. It makes your code more portable and flexible. However, to maintain existing code or for particular kinds of programs, you still might have to use SEH.

Microsoft-specific:

Grammar

try-except-statement :
 __trycompound-statement__except(filter-expression)compound-statement

try-finally-statement :
 __trycompound-statement__finallycompound-statement

Remarks

With SEH, you can ensure that resources, such as memory blocks and files, get released correctly if execution unexpectedly terminates. You can also handle specific problems—for example, insufficient memory—by using concise structured code that doesn't rely ongoto statements or elaborate testing of return codes.

Thetry-except andtry-finally statements referred to in this article are Microsoft extensions to the C and C++ languages. They support SEH by enabling applications to gain control of a program after events that would otherwise terminate execution. Although SEH works with C++ source files, it's not specifically designed for C++. If you use SEH in a C++ program that you compile by using the/EHa or/EHsc option, destructors for local objects are called, but other execution behavior might not be what you expect. For an illustration, see the example later in this article. In most cases, instead of SEH we recommend that you use ISO-standardC++ exception handling. By using C++ exception handling, you can ensure that your code is more portable, and you can handle exceptions of any type.

If you have C code that uses SEH, you can mix it with C++ code that uses C++ exception handling. For information, seeHandle structured exceptions in C++.

There are two SEH mechanisms:

• Exception handlers, or__except blocks, which can respond to or dismiss the exception based on thefilter-expression value. For more information, seetry-except statement.

• Termination handlers, or__finally blocks, which are always called, whether an exception causes termination or not. For more information, seetry-finally statement.

These two kinds of handlers are distinct, but are closely related through a process known asunwinding the stack. When a structured exception occurs, Windows looks for the most recently installed exception handler that's currently active. The handler can do one of three things:

• Fail to recognize the exception and pass control to other handlers (EXCEPTION_CONTINUE_SEARCH).

• Recognize the exception but dismiss it (EXCEPTION_CONTINUE_EXECUTION).

• Recognize the exception and handle it (EXCEPTION_EXECUTE_HANDLER).

The exception handler that recognizes the exception may not be in the function that was running when the exception occurred. It may be in a function much higher on the stack. The currently running function and all other functions on the stack frame are terminated. During this process, the stack isunwound. That is, local non-static variables of terminated functions get cleared from the stack.

As it unwinds the stack, the operating system calls any termination handlers that you've written for each function. By using a termination handler, you clean up resources that otherwise would remain open because of an abnormal termination. If you've entered a critical section, you can exit it in the termination handler. When the program is going to shut down, you can do other housekeeping tasks such as closing and removing temporary files.

Next steps

• Writing an exception handler

• Writing a termination handler

• Handle structured exceptions in C++

Example

As stated earlier, destructors for local objects are called if you use SEH in a C++ program and compile it by using the/EHa or/EHsc option. However, the behavior during execution may not be what you expect if you're also using C++ exceptions. This example demonstrates these behavioral differences.

#include <stdio.h>#include <Windows.h>#include <exception>class TestClass{public:    ~TestClass()    {        printf("Destroying TestClass!\n");    }};__declspec(noinline) void TestCPPEX(){#ifdef CPPEX    printf("Throwing C++ exception\n");    throw std::exception("");#else    printf("Triggering SEH exception\n");    volatile int *pInt = 0x00000000;    *pInt = 20;#endif}__declspec(noinline) void TestExceptions(){    TestClass d;    TestCPPEX();}int main(){    __try    {        TestExceptions();    }    __except(EXCEPTION_EXECUTE_HANDLER)    {        printf("Executing SEH __except block\n");    }    return 0;}

If you use/EHsc to compile this code but the local test control macroCPPEX is undefined, theTestClass destructor doesn't run. The output looks like this:

Triggering SEH exceptionExecuting SEH __except block

If you use/EHsc to compile the code andCPPEX is defined by using/DCPPEX (so that a C++ exception is thrown), theTestClass destructor runs, and the output looks like this:

Throwing C++ exceptionDestroying TestClass!Executing SEH __except block

If you use/EHa to compile the code, theTestClass destructor executes whether an exception was thrown using a standard C++throw expression or by using SEH. That is, whetherCPPEX is defined or not. The output looks like this:

Throwing C++ exceptionDestroying TestClass!Executing SEH __except block

For more information, see/EH (Exception Handling Model).

END Microsoft-specific

See also

Exception handling
Keywords
<exception>
Errors and exception handling
Structured Exception Handling (Windows)