__set_exception_handler() — Register an exception handler routine

Standards

Standards / Extensions	C or C++	Dependencies
	both

Format

#include <__le_api.h>

int  __set_exception_handler( void(*exception_handler) (struct __cib *, void *),
                              void * user_data);

General description

Restriction: This function is only valid for AMODE 64.

A nonstandard function that registers an 'Exception Handler' function for the current stack frame. Exception Handlers are used to process 'exceptions' at the thread level (unlike signal catchers which process signals at the process level).

Parameter: Description
exception_handle: Address of a function descriptor that is associated with an 'Exception Handler' function.
user_data: A user definable token that will be passed to the 'Exception Handler' function.

Exception Handlers are invoked for the following conditions:

Table 1. Invoked Exception Handlers
Exception	Feedback Code	Message Number	Resulting Signal
Operation	CEE341	CEE3201S	SIGILL
Privileged-operation	CEE342	CEE3202S	SIGILL
Execute	CEE343	CEE3203S	SIGILL
Protection	CEE344	CEE3204S	SIGSEGV
Addressing	CEE345	CEE3205S	SIGSEGV
Specification	CEE346	CEE3206S	SIGILL
Data	CEE347	CEE3207S	SIGFPE
Fixed-point overflow Note: Not processed in a C/C++ application.	CEE348	CEE3208S	SIGFPE
Fixed-point divide by zero	CEE349	CEE3209S	SIGFPE
Decimal overflow exception	CEE34A	CEE3210S	SIGFPE
Decimal divide by zero	CEE34B	CEE3211S	SIGFPE
Exponent overflow	CEE34C	CEE3212S	SIGFPE
Exponent underflow Note: Not processed in a C/C++ application.	CEE34D	CEE3213S	SIGFPE
Significance Note: Not processed in a C/C++ application.	CEE34E	CEE3214S	SIGFPE
Floating-point divide by zero	CEE34F	CEE3215S	SIGFPE
IEEE Binary Floating-Point inexact (truncated)	CEE34G	CEE3216S	SIGFPE
IEEE Binary Floating-Point inexact (incremented)	CEE34H	CEE3217S	SIGFPE
IEEE Binary Floating-Point exponent underflow	CEE34I	CEE3218S	SIGFPE
IEEE Binary Floating-Point exponent underflow inexact (truncated)	CEE34J	CEE3219S	SIGFPE
IEEE Binary Floating-Point exponent underflow inexact (incremented)	CEE34K	CEE3220S	SIGFPE
IEEE Binary Floating-Point exponent overflow	CEE34L	CEE3221S	SIGFPE
IEEE Binary Floating-Point exponent overflow inexact (truncated)	CEE34M	CEE3222S	SIGFPE
IEEE Binary Floating-Point exponent overflow inexact (incremented)	CEE34N	CEE3223S	SIGFPE
IEEE Binary Floating-Point divide by zero	CEE34O	CEE3224S	SIGFPE
IEEE Binary Floating-Point invalid operation	CEE34P	CEE3225S	SIGFPE
Compare and Trap Data Exception	CEE352	CEE3234S	SIGFPE
Vector-processing exception of IEEE invalid operation	CEE354	CEE3236S	SIGFPE
Vector-processing exception of IEEE division-by-zero	CEE355	CEE3237S	SIGFPE
Vector-processing exception of IEEE exponent-overflow	CEE356	CEE3238S	SIGFPE
Vector-processing exception of IEEE exponent-underflow	CEE357	CEE3239S	SIGFPE
Vector-processing exception of IEEE inexact	CEE358	CEE3240S	SIGFPE
Retryable abend	CEE35I	CEE3250C	SIGABND

When one of the exceptions listed above occurs, on a specific thread with a registered Exception Handler, Language Environment® will invoke the handler function with the following syntax:

void  exception_handler(struct __cib * cib, void * user_data);

Parameter: Description
cib: Address of the Language Environment Condition Information Block (CIB).
user_data: A user definable token that was specified when the Exception Handler was registered.

An Exception Handler function should never return to Language Environment. It should terminate the thread with pthread_exit(), terminate the process with exit(), or resume execution at a predefined point with setjmp() and longjmp(). If the Exception Handler returns to Language Environment, the thread will be abnormally terminated.

In a Posix environment only the thread is abnormally terminated, and the thread exit status is set to -1. Equivalent to:
```
pthread_exit( (void *) -1);
```
In a non-Posix environment the entire Language Environment (process as well as thread) is abnormally terminated. Equivalent to:
```
exit(-1);
```

Returned value

If successful, __set_exception_handler() returns 0. Otherwise, -1 is returned and errno is set to indicate the error. The following is a possible value for errno:

EINVAL — The Exception Handler is invalid.

Application usage

Multiple Exception Handlers may not be registered for a single stack frame. Only the last one registered is honored.
Exception Handlers may be nested, but they must be on different stack frames.
Once an Exception Handler is registered, it remains active across calls to nested functions, and will be automatically unregistered once the flow returns from the stack frame in which the call to __set_exception_handler() was invoked.
If an Exception Handler is registered, it remains active across subsequence function calls (nested function calls), unless one of the nested functions registers another exception handler. In which case the first exception handler is suspended.
Exception Handlers are automatically unregistered when a longjmp() returns to a stack frame earlier on the stack then the frame on which the Exception Handler was registered. All Exception Handlers that are associated with stack frames that are traversed as a result of a longjmp() are automatically unregistered.
When an Exception Handler is given control, it is disabled. Any other Exception Handler (that may have been previously registered) is not set active. In other words, when the Exception Handler is given control there is no Exception Handler active. It is suspended.
- Any exception that occurs while the Exception Handler is executing, will be processed in the same way that Language Environment processes exceptions when no Exception Handlers are present.
- If the Exception Handler needs to be able to handle exceptions that occur during the execution of the Exception Handler, the handler must invoke __set_exception_handler() to register another (or re-register the same) Exception Handler.
One and only one, Exception Handler will be invoked for a condition (the Handler that is active for the stack frame on which the condition (or exception) occurred).
If an Exception Handler exists and the condition is one of those listed above, all of the standard Language Environment condition processing is bypassed (including, when POSIX(ON), the mapping of the exception into a signal). Instead, the one active Exception Handler is given control, and it has one opportunity to 'handle' the exception. If it does not handle the exception then abnormal termination will occur.
Functions used to affect the processing of signals, have no impact on the processing of Exception Handlers. That is, blocking or ignoring SIGABND, SIGFPE, SIGILL, or SIGSEGV will not prevent Exception Handlers from getting control.
In order for Exception Handlers to work, the Language Environment 'TRAP' runtime option must be set on (i.e., TRAP(ON) or TRAP(ON, NOSPIE)).