usr/src/man/man3c/sigfpe.3c

   1 '\" te
   2 .\" Copyright (c) 1996, Sun Microsystems, Inc.
   3 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
   4 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
   5 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
   6 .TH SIGFPE 3C "May 4, 2004"
   7 .SH NAME
   8 sigfpe \- signal handling for specific SIGFPE codes
   9 .SH SYNOPSIS
  10 .LP
  11 .nf
  12 #include <floatingpoint.h>
  13 #include <siginfo.h>
  14
  15 \fBsigfpe_handler_type\fR \fBsigfpe\fR(\fBsigfpe_code_type\fR \fIcode\fR,
  16      \fBsigfpe_handler_type\fR \fIhdl\fR);
  17 .fi
  18
  19 .SH DESCRIPTION
  20 .sp
  21 .LP
  22 The \fBsigfpe()\fR function allows signal handling to be specified for
  23 particular \fBSIGFPE\fR codes.  A call to \fBsigfpe()\fR defines a new handler
  24 \fIhdl\fR for a particular \fBSIGFPE\fR \fIcode\fR and returns the old handler
  25 as the value of the function \fBsigfpe()\fR. Normally handlers are specified as
  26 pointers to functions; the special cases \fBSIGFPE_IGNORE\fR,
  27 \fBSIGFPE_ABORT\fR, and \fBSIGFPE_DEFAULT\fR allow ignoring, dumping core using
  28 \fBabort\fR(3C), or default handling respectively. Default handling is to dump
  29 core using \fBabort\fR(3C).
  30 .sp
  31 .LP
  32 The \fIcode\fR argument is usually one of the five \fBIEEE\|754-related\fR
  33 \fBSIGFPE\fR codes:
  34 .sp
  35 .in +2
  36 .nf
  37 FPE_FLTRES   fp_inexact \(mi floating-point inexact result
  38 FPE_FLTDIV   fp_division \(mi floating-point division by zero
  39 FPE_FLTUND   fp_underflow \(mi floating-point underflow
  40 FPE_FLTOVF   fp_overflow \(mi floating-point overflow
  41 FPE_FLTINV   fp_invalid \(mi floating-point invalid operation
  42 .fi
  43 .in -2
  44
  45 .sp
  46 .LP
  47 Three steps are required to intercept an \fBIEEE\|754-related\fR \fBSIGFPE\fR
  48 code with \fBsigfpe()\fR:
  49 .RS +4
  50 .TP
  51 1.
  52 Set up a handler with \fBsigfpe()\fR.
  53 .RE
  54 .RS +4
  55 .TP
  56 2.
  57 Enable the relevant \fBIEEE\|754\fR trapping capability in the hardware,
  58 perhaps by using assembly-language instructions.
  59 .RE
  60 .RS +4
  61 .TP
  62 3.
  63 Perform a floating-point operation that generates the intended
  64 \fBIEEE\|754\fR exception.
  65 .RE
  66 .sp
  67 .LP
  68 The \fBsigfpe()\fR function never changes floating-point hardware mode bits
  69 affecting \fBIEEE\|754\fR trapping.  No \fBIEEE\|754-related\fR \fBSIGFPE\fR
  70 signals will be generated unless those hardware mode bits are enabled.
  71 .sp
  72 .LP
  73 \fBSIGFPE\fR signals can be handled using \fBsigfpe()\fR, \fBsigaction\fR(2) or
  74 \fBsignal\fR(3C). In a particular program, to avoid confusion, use only one of
  75 these interfaces to handle \fBSIGFPE\fR signals.
  76 .SH EXAMPLES
  77 .LP
  78 \fBExample 1 \fRExample Of A User-Specified Signal Handler
  79 .sp
  80 .LP
  81 A user-specified signal handler might look like this:
  82
  83 .sp
  84 .in +2
  85 .nf
  86 #include <floatingpoint.h>
  87 #include <siginfo.h>
  88 #include <ucontext.h>
  89 /*
  90 * The sample_handler prints out a message then commits suicide.
  91 */
  92 void
  93 sample_handler(int sig, siginfo_t *sip, ucontext_t *uap) {
  94         char *label;
  95         switch (sip\(mi>si_code) {
  96         case FPE_FLTINV: label = "invalid operand"; break;
  97         case FPE_FLTRES: label = "inexact"; break;
  98         case FPE_FLTDIV: label = "division-by-zero"; break;
  99         case FPE_FLTUND: label = "underflow"; break;
 100         case FPE_FLTOVF: label = "overflow"; break;
 101         default: label = "???"; break;
 102         }
 103         fprintf(stderr,
 104         "FP exception %s (0x%x) occurred at address %p.\en",
 105         label, sip\(mi>si_code, (void *) sip\(mi>si_addr);
 106         abort();
 107 }
 108 .fi
 109 .in -2
 110
 111 .sp
 112 .LP
 113 and it might be set up like this:
 114
 115 .sp
 116 .in +2
 117 .nf
 118 #include <floatingpoint.h>
 119 #include <siginfo.h>
 120 #include <ucontext.h>
 121 extern void sample_handler(int, siginfo_t *, ucontext_t *);
 122 main(void) {
 123       sigfpe_handler_type hdl, old_handler1, old_handler2;
 124 /*
 125  * save current fp_overflow and fp_invalid handlers; set the new
 126 * fp_overflow handler to sample_handler(\|) and set the new
 127 * fp_invalid handler to SIGFPE_ABORT (abort on invalid)
 128 */
 129     hdl = (sigfpe_handler_type) sample_handler;
 130     old_handler1 = sigfpe(FPE_FLTOVF, hdl);
 131     old_handler2 = sigfpe(FPE_FLTINV, SIGFPE_ABORT);
 132     .\|.\|.
 133 /*
 134  * restore old fp_overflow and fp_invalid handlers
 135  */
 136      sigfpe(FPE_FLTOVF, old_handler1);
 137      sigfpe(FPE_FLTINV, old_handler2);
 138 }
 139 .fi
 140 .in -2
 141
 142 .SH FILES
 143 .sp
 144 .ne 2
 145 .na
 146 \fB\fB/usr/include/floatingpoint.h\fR\fR
 147 .ad
 148 .sp .6
 149 .RS 4n
 150
 151 .RE
 152
 153 .sp
 154 .ne 2
 155 .na
 156 \fB\fB/usr/include/siginfo.h\fR\fR
 157 .ad
 158 .sp .6
 159 .RS 4n
 160
 161 .RE
 162
 163 .SH ATTRIBUTES
 164 .sp
 165 .LP
 166 See \fBattributes\fR(5) for descriptions of the following attributes:
 167 .sp
 168
 169 .sp
 170 .TS
 171 box;
 172 c | c
 173 l | l .
 174 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 175 _
 176 MT-Level        Safe
 177 .TE
 178
 179 .SH SEE ALSO
 180 .sp
 181 .LP
 182 \fBsigaction\fR(2), \fBabort\fR(3C), \fBsignal\fR(3C), \fBattributes\fR(5),
 183 \fBfloatingpoint.h\fR(3HEAD)
 184 .SH DIAGNOSTICS
 185 .sp
 186 .LP
 187 The \fBsigfpe()\fR function returns (void(*)())-1 if \fIcode\fR is not zero or
 188 a defined \fBSIGFPE\fR code.