1 '\" te
   2 .\" Copyright (c) 2006, Sun Microsystems, Inc. All Rights Reserved.
   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 fex_set_handling 3M "12 Jul 2006" "SunOS 5.11" "Mathematical Library Functions"
   7 .SH NAME
   8 fex_set_handling, fex_get_handling, fex_getexcepthandler, fex_setexcepthandler
   9 \- control floating point exception handling modes
  10 .SH SYNOPSIS
  11 .LP
  12 .nf
  13 c99 [ \fIflag\fR... ] \fIfile\fR... -lm [ \fIlibrary\fR... ]
  14 #include <fenv.h> 
  15 
  16 \fBint\fR \fBfex_set_handling\fR(\fBint\fR \fIex\fR, \fBint\fR \fImode\fR, \fBvoid(*\fR\fIhandler\fR);
  17 .fi
  18 
  19 .LP
  20 .nf
  21 \fBint\fR \fBfex_get_handling\fR(\fBint\fR \fIex\fR);
  22 .fi
  23 
  24 .LP
  25 .nf
  26 \fBvoid\fR \fBfex_getexcepthandler\fR(\fBfex_handler_t *\fR\fIbuf\fR, \fBint\fR \fIex\fR);
  27 .fi
  28 
  29 .LP
  30 .nf
  31 \fBvoid\fR \fBfex_setexcepthandler\fR(\fBconst fex_handler_t *\fR\fIbuf\fR, \fBint\fR \fIex\fR);
  32 .fi
  33 
  34 .SH DESCRIPTION
  35 .sp
  36 .LP
  37 These functions provide control of floating point exception handling modes. For
  38 each function, the \fIex\fR argument specifies one or more exceptions indicated
  39 by a bitwise-OR of any of the following values defined in <\fBfenv.h\fR>:
  40 .sp
  41 .ne 2
  42 .mk
  43 .na
  44 \fB\fBFEX_INEXACT\fR\fR
  45 .ad
  46 .RS 17n
  47 .rt  
  48 
  49 .RE
  50 
  51 .sp
  52 .ne 2
  53 .mk
  54 .na
  55 \fB\fBFEX_UNDERFLOW\fR\fR
  56 .ad
  57 .RS 17n
  58 .rt  
  59 
  60 .RE
  61 
  62 .sp
  63 .ne 2
  64 .mk
  65 .na
  66 \fB\fBFEX_OVERFLOW\fR\fR
  67 .ad
  68 .RS 17n
  69 .rt  
  70 
  71 .RE
  72 
  73 .sp
  74 .ne 2
  75 .mk
  76 .na
  77 \fB\fBFEX_DIVBYZERO\fR\fR
  78 .ad
  79 .RS 17n
  80 .rt  
  81 division by zero
  82 .RE
  83 
  84 .sp
  85 .ne 2
  86 .mk
  87 .na
  88 \fB\fBFEX_INV_ZDZ\fR\fR
  89 .ad
  90 .RS 17n
  91 .rt  
  92 0/0 invalid operation
  93 .RE
  94 
  95 .sp
  96 .ne 2
  97 .mk
  98 .na
  99 \fB\fBFEX_INV_IDI\fR\fR
 100 .ad
 101 .RS 17n
 102 .rt  
 103 infinity/infinity invalid operation
 104 .RE
 105 
 106 .sp
 107 .ne 2
 108 .mk
 109 .na
 110 \fB\fBFEX_INV_ISI\fR\fR
 111 .ad
 112 .RS 17n
 113 .rt  
 114 infinity-infinity invalid operation
 115 .RE
 116 
 117 .sp
 118 .ne 2
 119 .mk
 120 .na
 121 \fB\fBFEX_INV_ZMI\fR\fR
 122 .ad
 123 .RS 17n
 124 .rt  
 125 0*infinity invalid operation
 126 .RE
 127 
 128 .sp
 129 .ne 2
 130 .mk
 131 .na
 132 \fB\fBFEX_INV_SQRT\fR\fR
 133 .ad
 134 .RS 17n
 135 .rt  
 136 square root of negative operand
 137 .RE
 138 
 139 .sp
 140 .ne 2
 141 .mk
 142 .na
 143 \fB\fBFEX_INV_SNAN\fR\fR
 144 .ad
 145 .RS 17n
 146 .rt  
 147 signaling NaN
 148 .RE
 149 
 150 .sp
 151 .ne 2
 152 .mk
 153 .na
 154 \fB\fBFEX_INV_INT\fR\fR
 155 .ad
 156 .RS 17n
 157 .rt  
 158 invalid integer conversion
 159 .RE
 160 
 161 .sp
 162 .ne 2
 163 .mk
 164 .na
 165 \fB\fBFEX_INV_CMP\fR\fR
 166 .ad
 167 .RS 17n
 168 .rt  
 169 invalid comparison
 170 .RE
 171 
 172 .sp
 173 .LP
 174 For convenience, the following combinations of values are also defined:
 175 .sp
 176 .ne 2
 177 .mk
 178 .na
 179 \fB\fBFEX_NONE\fR\fR
 180 .ad
 181 .RS 15n
 182 .rt  
 183 no exceptions
 184 .RE
 185 
 186 .sp
 187 .ne 2
 188 .mk
 189 .na
 190 \fB\fBFEX_INVALID\fR\fR
 191 .ad
 192 .RS 15n
 193 .rt  
 194 all invalid operation exceptions
 195 .RE
 196 
 197 .sp
 198 .ne 2
 199 .mk
 200 .na
 201 \fB\fBFEX_COMMON\fR\fR
 202 .ad
 203 .RS 15n
 204 .rt  
 205 overflow, division by zero, and invalid operation
 206 .RE
 207 
 208 .sp
 209 .ne 2
 210 .mk
 211 .na
 212 \fB\fBFEX_ALL\fR\fR
 213 .ad
 214 .RS 15n
 215 .rt  
 216 all exceptions
 217 .RE
 218 
 219 .sp
 220 .LP
 221 The \fBfex_set_handling()\fR function establishes the specified \fImode\fR for
 222 handling the floating point exceptions identified by \fIex\fR.  The selected
 223 \fImode\fR determines the action to be taken when one of the indicated
 224 exceptions occurs.  It must be one of the following values:
 225 .sp
 226 .ne 2
 227 .mk
 228 .na
 229 \fB\fBFEX_NOHANDLER\fR\fR
 230 .ad
 231 .RS 17n
 232 .rt  
 233 Trap but do not otherwise handle the exception, evoking instead whatever
 234 ambient behavior would normally be in effect.  This is the default behavior
 235 when the exception's trap is enabled. The \fIhandler\fR parameter is ignored.
 236 .RE
 237 
 238 .sp
 239 .ne 2
 240 .mk
 241 .na
 242 \fB\fBFEX_NONSTOP\fR\fR
 243 .ad
 244 .RS 17n
 245 .rt  
 246 Provide the IEEE 754 default result for the operation that caused the
 247 exception, set the exception's flag, and continue execution. This is the
 248 default behavior when the exception's trap is disabled.  The \fIhandler\fR
 249 parameter is ignored.
 250 .RE
 251 
 252 .sp
 253 .ne 2
 254 .mk
 255 .na
 256 \fB\fBFEX_ABORT\fR\fR
 257 .ad
 258 .RS 17n
 259 .rt  
 260 Call \fBabort\fR(3C). The \fIhandler\fR parameter is ignored.
 261 .RE
 262 
 263 .sp
 264 .ne 2
 265 .mk
 266 .na
 267 \fB\fBFEX_SIGNAL\fR\fR
 268 .ad
 269 .RS 17n
 270 .rt  
 271 Invoke the function *\fIhandler\fR with the parameters normally supplied to a
 272 signal handler installed with \fBsigfpe\fR(3C).
 273 .RE
 274 
 275 .sp
 276 .ne 2
 277 .mk
 278 .na
 279 \fB\fBFEX_CUSTOM\fR\fR
 280 .ad
 281 .RS 17n
 282 .rt  
 283 Invoke the function *\fIhandler\fR as described in the next paragraph.
 284 .RE
 285 
 286 .sp
 287 .LP
 288 In \fBFEX_CUSTOM\fR mode, when a floating point exception occurs, the handler
 289 function is invoked as though its prototype were:
 290 .sp
 291 .in +2
 292 .nf
 293 #include <fenv.h>
 294 void handler(int ex, fex_info_t *info);
 295 .fi
 296 .in -2
 297 
 298 .sp
 299 .LP
 300 On entry, \fIex\fR is the value (of the first twelve listed above)
 301 corresponding to the exception that occurred, \fBinfo->op\fR indicates the
 302 operation that caused the exception, \fBinfo->op1\fR and \fBinfo->op2\fR
 303 contain the values of the operands, \fBinfo->res\fR contains the default
 304 untrapped result value, and \fBinfo->flags\fR reflects the exception flags that
 305 the operation would have set had it not been trapped.  If the handler returns,
 306 the value contained in \fBinfo->res\fR on exit is substituted for the result of
 307 the operation, the flags indicated by \fBinfo->flags\fR are set, and execution
 308 resumes at the point where the exception occurred.  The handler might modify
 309 \fBinfo->res\fR and \fBinfo->flags\fR to supply any desired result value and
 310 flags.  Alternatively, if the exception is underflow or overflow, the hander
 311 might set
 312 .sp
 313 .LP
 314 info->res.type = fex_nodata;
 315 .sp
 316 .LP
 317 which causes the exponent-adjusted result specified by IEEE 754 to be
 318 substituted.  If the handler does not modify \fBinfo->res\fR or
 319 \fBinfo->flags\fR, the effect is the same as if the exception had not been
 320 trapped.
 321 .sp
 322 .LP
 323 Although the default untrapped result of an exceptional operation is always
 324 available to a \fBFEX_CUSTOM\fR handler, in some cases, one or both operands
 325 may not be.  In these cases, the handler may be invoked with \fBinfo->op1.type
 326 == fex_nodata\fR or \fBinfo->op2.type == fex_nodata\fR to indicate that the
 327 respective data structures do not contain valid data.  (For example,
 328 \fBinfo->op2.type == fex_nodata\fR if the exceptional operation is a unary
 329 operation.)  Before accessing the operand values, a custom handler should
 330 always examine the \fBtype\fR field of the operand data structures to ensure
 331 that they contain valid data in the appropriate format.
 332 .sp
 333 .LP
 334 The \fBfex_get_handling()\fR function returns the current handling mode for the
 335 exception specified by \fIex\fR, which must be one of the first twelve
 336 exceptions listed above.
 337 .sp
 338 .LP
 339 The \fBfex_getexcepthandler()\fR function saves the current handling modes and
 340 associated data for the exceptions specified by \fIex\fR in the data structure
 341 pointed to by \fIbuf\fR. The type \fBfex_handler_t\fR is defined in
 342 <\fBfenv.h\fR>.
 343 .sp
 344 .LP
 345 The \fBfex_setexcepthandler()\fR function restores the handling modes and
 346 associated data for the exceptions specified by \fIex\fR from the data
 347 structure pointed to by \fIbuf\fR.  This data structure must have been set by a
 348 previous call to \fBfex_getexcepthandler()\fR. Otherwise the effect on the
 349 indicated modes is undefined.
 350 .SH RETURN VALUES
 351 .sp
 352 .LP
 353 The \fBfex_set_handling()\fR function returns a non-zero value if the requested
 354 exception handling mode is established. Otherwise, it returns 0.
 355 .SH EXAMPLES
 356 .sp
 357 .LP
 358 The following example demonstrates how to substitute a predetermined value for
 359 the result of a 0/0 invalid operation.
 360 .sp
 361 .in +2
 362 .nf
 363 #include <math.h>
 364 #include <fenv.h>
 365 
 366 double k;
 367 
 368 void presub(int ex, fex_info_t *info) {
 369         info->res.type = fex_double;
 370         info->res.val.d = k;
 371 }
 372 
 373 int main() {
 374         double x, w;
 375         int i;
 376         fex_handler_t buf;
 377 /*
 378  * save current 0/0 handler
 379  */
 380         (void) fex_getexcepthandler(&buf, FEX_INV_ZDZ);
 381 /* 
 382  * set up presubstitution handler for 0/0
 383  */
 384         (void) fex_set_handling(FEX_INV_ZDZ, FEX_CUSTOM, presub);
 385 /*
 386  *  compute (k*x)/sin(x) for k=2.0, x=0.5, 0.4, ..., 0.1, 0.0
 387  */
 388         k = 2.0;
 389         (void) printf("Evaluating f(x) = (k*x)/sin(x)\en\en");
 390         for (i = 5; i >= 0; i--) {
 391                 x = (double) i * 0.1;
 392                 w = (k * x) / sin(x);
 393                 (void) printf("\etx=%3.3f\et f(x) = % 1.20e\en", x, w);
 394         }
 395 /*
 396  * restore old 0/0 handler 
 397  */
 398         (void) fex_setexcepthandler(&buf, FEX_INV_ZDZ);
 399         return 0;
 400 }
 401 .fi
 402 .in -2
 403 
 404 .sp
 405 .LP
 406 The output from the preceding program reads:
 407 .sp
 408 .in +2
 409 .nf
 410 Evaluating f(x) = (k*x)/sin(x)
 411 
 412         x=0.500  f(x) =  2.08582964293348816000e+00
 413         x=0.400  f(x) =  2.05434596443822626000e+00
 414         x=0.300  f(x) =  2.03031801709447368000e+00
 415         x=0.200  f(x) =  2.01339581906893761000e+00
 416         x=0.100  f(x) =  2.00333722632695554000e+00
 417         x=0.000  f(x) =  2.00000000000000000000e+00
 418 .fi
 419 .in -2
 420 
 421 .sp
 422 .LP
 423 When \fIx\fR = 0, \fIf(x)\fR is computed as 0/0 and an invalid operation
 424 exception occurs.  In this example, the value 2.0 is substituted for the
 425 result.
 426 .SH ATTRIBUTES
 427 .sp
 428 .LP
 429 See \fBattributes\fR(5) for descriptions of the following attributes:
 430 .sp
 431 
 432 .sp
 433 .TS
 434 tab() box;
 435 lw(2.75i) lw(2.75i) 
 436 lw(2.75i) lw(2.75i) 
 437 .
 438 ATTRIBUTE TYPEATTRIBUTE VALUE
 439 AvailabilitySUNWlibms, SUNWlmxs
 440 Interface StabilityStable
 441 MT-LevelMT-Safe (see Notes)
 442 .TE
 443 
 444 .SH SEE ALSO
 445 .sp
 446 .LP
 447 \fBsigfpe\fR(3C), \fBfeclearexcept\fR(3M), \fBfegetenv\fR(3M),
 448 \fBfex_set_log\fR(3M), \fBattributes\fR(5)
 449 .sp
 450 .LP
 451 \fINumerical Computation Guide\fR
 452 .SH NOTES
 453 .sp
 454 .LP
 455 In a multithreaded application, the preceding functions affect exception
 456 handling modes only for the calling thread.
 457 .sp
 458 .LP
 459 The functions described on this page automatically install and deinstall
 460 \fBSIGFPE\fR handlers and set and clear the trap enable mode bits in the
 461 floating point status register as needed.  If a program uses these functions
 462 and attempts to install a \fBSIGFPE\fR handler or control the trap enable mode
 463 bits independently, the resulting behavior is not defined.
 464 .sp
 465 .LP
 466 All traps are disabled before a handler installed in \fBFEX_CUSTOM\fR mode is
 467 invoked.  When the \fBSIGFPE\fR signal is blocked, as it is when such a handler
 468 is invoked, the floating point environment, exception flags, and retrospective
 469 diagnostic functions described in \fBfeclearexcept\fR(3M), \fBfegetenv\fR(3M),
 470 and \fBfex_set_log\fR(3M) do not re-enable traps.  Thus, the handler itself
 471 always runs in \fBFEX_NONSTOP\fR mode with logging of retrospective diagnostics
 472 disabled.  Attempting to change these modes within the handler may not produce
 473 the expected results.