__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:
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)).
Related information
- exit() — End program
- longjmp() — Restore stack environment
- _longjmp() — Nonlocal goto
- pthread_exit() — Exit a thread
- __reset_exception_handler() — Unregister an exception handler routine
- setjmp() — Preserve stack environment
- siglongjmp() — Restore the stack environment and signal mask
- sigsetjmp() — Save stack environment and signal mask