Current File : //usr/man/man3c/sigfpe.3c

'\" te
.\" Copyright (c) 1996, Sun Microsystems, Inc.
.TH sigfpe 3C "4 May 2004" "SunOS 5.11" "Standard C Library Functions"
.SH NAME
sigfpe \- signal handling for specific SIGFPE codes
.SH SYNOPSIS
.LP
.nf
#include <floatingpoint.h>
#include <siginfo.h>

\fBsigfpe_handler_type\fR \fBsigfpe\fR(\fBsigfpe_code_type\fR \fIcode\fR,
     \fBsigfpe_handler_type\fR \fIhdl\fR);
.fi

.SH DESCRIPTION
.sp
.LP
The \fBsigfpe()\fR function allows signal handling to be specified for particular \fBSIGFPE\fR codes.  A call to \fBsigfpe()\fR defines a new handler \fIhdl\fR for a particular \fBSIGFPE\fR \fIcode\fR and returns the old handler as the value of the function \fBsigfpe()\fR. Normally handlers are specified as pointers to functions; the special cases \fBSIGFPE_IGNORE\fR, \fBSIGFPE_ABORT\fR, and \fBSIGFPE_DEFAULT\fR allow ignoring, dumping core using \fBabort\fR(3C), or default handling respectively. Default handling is to dump core using \fBabort\fR(3C).
.sp
.LP
The \fIcode\fR argument is usually one of the five \fBIEEE\|754-related\fR \fBSIGFPE\fR codes:
.sp
.in +2
.nf
FPE_FLTRES   fp_inexact \(mi floating-point inexact result
FPE_FLTDIV   fp_division \(mi floating-point division by zero        
FPE_FLTUND   fp_underflow \(mi floating-point underflow
FPE_FLTOVF   fp_overflow \(mi floating-point overflow
FPE_FLTINV   fp_invalid \(mi floating-point invalid operation
.fi
.in -2

.sp
.LP
Three steps are required to intercept an \fBIEEE\|754-related\fR \fBSIGFPE\fR code with \fBsigfpe()\fR:
.RS +4
.TP
1.
Set up a handler with \fBsigfpe()\fR.
.RE
.RS +4
.TP
2.
Enable the relevant \fBIEEE\|754\fR trapping capability in the hardware, perhaps by using assembly-language instructions.
.RE
.RS +4
.TP
3.
Perform a floating-point operation that generates the intended \fBIEEE\|754\fR exception.
.RE
.sp
.LP
The \fBsigfpe()\fR function never changes floating-point hardware mode bits affecting \fBIEEE\|754\fR trapping.  No \fBIEEE\|754-related\fR \fBSIGFPE\fR signals will be generated unless those hardware mode bits are enabled.
.sp
.LP
\fBSIGFPE\fR signals can be handled using \fBsigfpe()\fR, \fBsigaction\fR(2) or \fBsignal\fR(3C). In a particular program, to avoid confusion, use only one of these interfaces to handle \fBSIGFPE\fR signals.
.SH EXAMPLES
.LP
\fBExample 1 \fRExample Of A User-Specified Signal Handler
.sp
.LP
A user-specified signal handler might look like this:

.sp
.in +2
.nf
#include <floatingpoint.h>
#include <siginfo.h>
#include <ucontext.h>
/*
* The sample_handler prints out a message then commits suicide.
*/
void
sample_handler(int sig, siginfo_t *sip, ucontext_t *uap) {
	char *label;
        switch (sip\(mi>si_code) {
	case FPE_FLTINV: label = "invalid operand"; break;
	case FPE_FLTRES: label = "inexact"; break;
	case FPE_FLTDIV: label = "division-by-zero"; break;
	case FPE_FLTUND: label = "underflow"; break;
	case FPE_FLTOVF: label = "overflow"; break;
	default: label = "???"; break;
	}
	fprintf(stderr, 
        "FP exception %s (0x%x) occurred at address %p.\en",
        label, sip\(mi>si_code, (void *) sip\(mi>si_addr);
	abort();
}
.fi
.in -2

.sp
.LP
and it might be set up like this: 

.sp
.in +2
.nf
#include <floatingpoint.h>
#include <siginfo.h>
#include <ucontext.h>
extern void sample_handler(int, siginfo_t *, ucontext_t *);
main(void) {
      sigfpe_handler_type hdl, old_handler1, old_handler2;
/*
 * save current fp_overflow and fp_invalid handlers; set the new
* fp_overflow handler to sample_handler(\|) and set the new
* fp_invalid handler to SIGFPE_ABORT (abort on invalid)
*/
    hdl = (sigfpe_handler_type) sample_handler;
    old_handler1 = sigfpe(FPE_FLTOVF, hdl);
    old_handler2 = sigfpe(FPE_FLTINV, SIGFPE_ABORT);
    .\|.\|.
/*
 * restore old fp_overflow and fp_invalid handlers
 */
     sigfpe(FPE_FLTOVF, old_handler1);
     sigfpe(FPE_FLTINV, old_handler2);
}
.fi
.in -2

.SH FILES
.sp
.ne 2
.mk
.na
\fB\fB/usr/include/floatingpoint.h\fR\fR
.ad
.sp .6
.RS 4n

.RE

.sp
.ne 2
.mk
.na
\fB\fB/usr/include/siginfo.h\fR\fR
.ad
.sp .6
.RS 4n

.RE

.SH ATTRIBUTES
.sp
.LP
See \fBattributes\fR(5) for descriptions of the following attributes:
.sp

.sp
.TS
tab() box;
cw(2.75i) |cw(2.75i) 
lw(2.75i) |lw(2.75i) 
.
ATTRIBUTE TYPEATTRIBUTE VALUE
_
MT-LevelSafe
.TE

.SH SEE ALSO
.sp
.LP
\fBsigaction\fR(2), \fBabort\fR(3C), \fBsignal\fR(3C), \fBattributes\fR(5), \fBfloatingpoint.h\fR(3HEAD)
.SH DIAGNOSTICS
.sp
.LP
The \fBsigfpe()\fR function returns (void(*)())-1 if \fIcode\fR is not zero or a defined \fBSIGFPE\fR code.