share/man/man3m/matherr.3m

   1 '\" te
   2 .\"  Copyright (c) 2008, 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 MATHERR 3M "Sep 23, 1997" "SunOS 5.11" "Mathematical Library Functions"
   7 .SH NAME
   8 matherr \- math library exception-handling function
   9 .SH SYNOPSIS
  10 .LP
  11 .nf
  12 #include <math.h>
  13
  14 \fBint\fR \fBmatherr\fR(\fBstruct exception *\fR\fIexc\fR);
  15 .fi
  16
  17 .SH DESCRIPTION
  18 .sp
  19 .LP
  20 The System V Interface Definition, Third Edition (SVID3) specifies that certain
  21 \fBlibm\fR functions call \fBmatherr()\fR when exceptions are detected. Users
  22 may define their own mechanisms for handling exceptions, by including a
  23 function named \fBmatherr()\fR in their programs. The \fBmatherr()\fR function
  24 is of the form described above. When an exception occurs, a pointer to the
  25 exception structure \fIexc\fR will be passed to the user-supplied
  26 \fBmatherr()\fR function.  This structure, which is defined in the
  27 \fB<math.h>\fR header file, is as follows:
  28 .sp
  29 .in +2
  30 .nf
  31 struct exception {
  32         int type;
  33         char *name;
  34         double arg1, arg2, retval;
  35 };
  36 .fi
  37 .in -2
  38
  39 .sp
  40 .LP
  41 The \fBtype\fR member is an integer describing the type of exception that has
  42 occurred, from the following list of constants (defined in the header file):
  43 .sp
  44 .ne 2
  45 .mk
  46 .na
  47 \fB\fBDOMAIN\fR\fR
  48 .ad
  49 .RS 13n
  50 .rt
  51 argument domain exception
  52 .RE
  53
  54 .sp
  55 .ne 2
  56 .mk
  57 .na
  58 \fB\fBSING\fR\fR
  59 .ad
  60 .RS 13n
  61 .rt
  62 argument singularity
  63 .RE
  64
  65 .sp
  66 .ne 2
  67 .mk
  68 .na
  69 \fB\fBOVERFLOW\fR\fR
  70 .ad
  71 .RS 13n
  72 .rt
  73 overflow range exception
  74 .RE
  75
  76 .sp
  77 .ne 2
  78 .mk
  79 .na
  80 \fB\fBUNDERFLOW\fR\fR
  81 .ad
  82 .RS 13n
  83 .rt
  84 underflow range exception
  85 .RE
  86
  87 .sp
  88 .ne 2
  89 .mk
  90 .na
  91 \fB\fBTLOSS\fR\fR
  92 .ad
  93 .RS 13n
  94 .rt
  95 total loss of significance
  96 .RE
  97
  98 .sp
  99 .ne 2
 100 .mk
 101 .na
 102 \fB\fBPLOSS\fR\fR
 103 .ad
 104 .RS 13n
 105 .rt
 106 partial loss of significance
 107 .RE
 108
 109 .sp
 110 .LP
 111 Both \fBTLOSS\fR and \fBPLOSS\fR reflect limitations of particular algorithms
 112 for trigonometric functions that suffer abrupt declines in accuracy at definite
 113 boundaries. Since the implementation does not suffer such abrupt declines,
 114 \fBPLOSS\fR is never signaled. \fBTLOSS\fR is signaled for Bessel functions
 115 \fIonly\fR to satisfy SVID3 requirements.
 116 .sp
 117 .LP
 118 The \fBname\fR member points to a string containing the name of the function
 119 that incurred the exception. The \fBarg1\fR and \fBarg2\fR members are the
 120 arguments with which the function was invoked. \fBretval\fR is set to the
 121 default value that will be returned by the function unless the user's
 122 \fBmatherr()\fR sets it to a different value.
 123 .sp
 124 .LP
 125 If the user's \fBmatherr()\fR function returns non-zero, no exception message
 126 will be printed and \fBerrno\fR is not set.
 127 .SH SVID3 STANDARD CONFORMANCE
 128 .sp
 129 .LP
 130 When an application is built as a SVID3 conforming application (see
 131 \fBstandards\fR(5)), if \fBmatherr()\fR is not supplied by the user, the
 132 default matherr exception-handling mechanisms, summarized in the table below,
 133 are invoked upon exception:
 134 .sp
 135 .ne 2
 136 .mk
 137 .na
 138 \fB\fBDOMAIN\fR\fR
 139 .ad
 140 .RS 13n
 141 .rt
 142 0.0 is usually returned, \fBerrno\fR is set to \fBEDOM\fR and a message is
 143 usually printed on standard error.
 144 .RE
 145
 146 .sp
 147 .ne 2
 148 .mk
 149 .na
 150 \fB\fBSING\fR\fR
 151 .ad
 152 .RS 13n
 153 .rt
 154 The largest finite single-precision number, \fBHUGE\fR of appropriate sign, is
 155 returned, \fBerrno\fR is set to \fBEDOM\fR, and a message is printed on
 156 standard error.
 157 .RE
 158
 159 .sp
 160 .ne 2
 161 .mk
 162 .na
 163 \fB\fBOVERFLOW\fR\fR
 164 .ad
 165 .RS 13n
 166 .rt
 167 The largest finite single-precision number, \fBHUGE\fR of appropriate sign, is
 168 usually returned and \fBerrno\fR is set to \fBERANGE\fR.
 169 .RE
 170
 171 .sp
 172 .ne 2
 173 .mk
 174 .na
 175 \fB\fBUNDERFLOW\fR\fR
 176 .ad
 177 .RS 13n
 178 .rt
 179 0.0 is returned and \fBerrno\fR is set to \fBERANGE\fR.
 180 .RE
 181
 182 .sp
 183 .ne 2
 184 .mk
 185 .na
 186 \fB\fBTLOSS\fR\fR
 187 .ad
 188 .RS 13n
 189 .rt
 190 0.0 is returned, \fBerrno\fR is set to \fBERANGE\fR, and a message is printed
 191 on standard error.
 192 .RE
 193
 194 .sp
 195 .LP
 196 In general, \fBerrno\fR is not a reliable error indicator because it can be
 197 unexpectedly set by a function in a handler for an asynchronous signal.
 198 .SS "SVID3 ERROR HANDLING PROCEDURES (compile with cc \e-Xt)"
 199 .sp
 200
 201 .sp
 202 .TS
 203 tab(    ) box;
 204 cw(1.29i) |cw(.81i) |cw(.79i) |cw(.87i) |cw(1.03i) |cw(.71i)
 205 lw(1.29i) |lw(.81i) |lw(.79i) |lw(.87i) |lw(1.03i) |lw(.71i)
 206 .
 207 <math.h> type   DOMAIN  SING    OVERFLOW        UNDERFLOW       TLOSS
 208 _
 209 \fBerrno\fR     EDOM    EDOM    ERANGE  ERANGE  ERANGE
 210 _
 211 IEEE Exception  Invalid Operation       Division by Zero        Overflow        Underflow       \(mi
 212 _
 213 fp_exception_type       fp_invalid      fp_division     fp_overflow     fp_underflow    \(mi
 214 _
 215 ACOS, ASIN\|(|x| > 1):  Md, 0.0 \(mi    \(mi    \(mi    \(mi
 216 _
 217 ACOSH\|(x < 1), ATANH\|(|x| > 1):       NaN     \(mi    \(mi    \(mi    \(mi
 218 _
 219 ATAN2\|(0,0):   Md, 0.0 \(mi    \(mi    \(mi    \(mi
 220 _
 221 COSH, SINH:     \(mi    \(mi    \(+-HUGE        \(mi    \(mi
 222 _
 223 EXP:    \(mi    \(mi    +HUGE   0.0     \(mi
 224 _
 225 FMOD\|(x,0):    x       \(mi    \(mi    \(mi    \(mi
 226 _
 227 HYPOT:  \(mi    \(mi    +HUGE   \(mi    \(mi
 228 _
 229 J0, J1, JN\|(|x| > X_TLOSS):    \(mi    \(mi    \(mi    \(mi    Mt, 0.0
 230 _
 231 LGAMMA:
 232  usual cases    \(mi    \(mi    +HUGE   \(mi    \(mi
 233  (x = 0 or \(miinteger) \(mi    Ms, +HUGE       \(mi    \(mi    \(mi
 234 _
 235 LOG, LOG10:
 236  (x < 0)        Md, \(miHUGE    \(mi     \(mi   \(mi    \(mi
 237  (x = 0)        \(mi    Ms, \(miHUGE    \(mi    \(mi    \(mi
 238 _
 239 POW:
 240  usual cases    \(mi    \(mi    \(+-HUGE        \(+-0.0 \(mi
 241  (x < 0) ** (y not an integer)  Md, 0.0 \(mi    \(mi    \(mi    \(mi
 242  0 ** 0 Md, 0.0 \(mi    \(mi    \(mi    \(mi
 243  0 ** (y < 0)   Md, 0.0 \(mi    \(mi    \(mi
 244 _
 245 REMAINDER\|(x,0):       NaN     \(mi    \(mi    \(mi    \(mi
 246 _
 247 SCALB:  \(mi    \(mi    \(+-HUGE_VAL    \(+-0.0 \(mi
 248 _
 249 SQRT\|(x < 0):  Md, 0.0 \(mi    \(mi    \(mi    \(mi
 250 _
 251 Y0, Y1, YN:
 252  (x < 0)        Md, \(miHUGE    \(mi    \(mi    \(mi    \(mi
 253  (x = 0)        \(mi    Md, \(miHUGE    \(mi    \(mi    \(mi
 254  (x > X_TLOSS)  \(mi    \(mi    \(mi    \(mi    Mt, 0.0
 255 .TE
 256
 257 .SS "Abbreviations"
 258 .sp
 259 .ne 2
 260 .mk
 261 .na
 262 \fBMd\fR
 263 .ad
 264 .RS 12n
 265 .rt
 266 Message is printed (DOMAIN error).
 267 .RE
 268
 269 .sp
 270 .ne 2
 271 .mk
 272 .na
 273 \fBMs\fR
 274 .ad
 275 .RS 12n
 276 .rt
 277 Message is printed (SING error).
 278 .RE
 279
 280 .sp
 281 .ne 2
 282 .mk
 283 .na
 284 \fBMt\fR
 285 .ad
 286 .RS 12n
 287 .rt
 288 Message is printed (TLOSS error).
 289 .RE
 290
 291 .sp
 292 .ne 2
 293 .mk
 294 .na
 295 \fBNaN\fR
 296 .ad
 297 .RS 12n
 298 .rt
 299 IEEE NaN result and invalid operation exception.
 300 .RE
 301
 302 .sp
 303 .ne 2
 304 .mk
 305 .na
 306 \fBHUGE\fR
 307 .ad
 308 .RS 12n
 309 .rt
 310 Maximum finite single-precision floating-point number.
 311 .RE
 312
 313 .sp
 314 .ne 2
 315 .mk
 316 .na
 317 \fBHUGE_VAL\fR
 318 .ad
 319 .RS 12n
 320 .rt
 321 IEEE \(if result and division-by-zero exception.
 322 .RE
 323
 324 .sp
 325 .ne 2
 326 .mk
 327 .na
 328 \fBX_TLOSS\fR
 329 .ad
 330 .RS 12n
 331 .rt
 332 The value X_TLOSS is defined in <values.h>.
 333 .RE
 334
 335 .sp
 336 .LP
 337 The interaction of IEEE arithmetic and \fBmatherr()\fR is not defined when
 338 executing under IEEE rounding modes other than the default round to nearest:
 339 \fBmatherr()\fR is not always called on overflow or underflow and can return
 340 results that differ from those in this table.
 341 .SH X/OPEN COMMON APPLICATION ENVIRONMENT (CAE) SPECIFICATIONS CONFORMANCE
 342 .sp
 343 .LP
 344 The X/Open System Interfaces and Headers (XSH) Issue 3 and later revisions of
 345 that specification no longer sanctions the use of the \fBmatherr\fR interface.
 346 The following table summarizes the values returned in the exceptional cases.
 347 In general, XSH dictates that as long as one of the input argument(s) is a NaN,
 348 NaN is returned. In particular, \fBpow(NaN,0)\fR = NaN.
 349 .SS "CAE SPECIFICATION ERROR HANDLING PROCEDURES (compile with cc \fB-Xa\fR)"
 350 .sp
 351
 352 .sp
 353 .TS
 354 tab(    ) box;
 355 cw(.82i) |cw(1.03i) |cw(1i) |cw(.97i) |cw(.96i) |cw(.72i)
 356 lw(.82i) |lw(1.03i) |lw(1i) |lw(.97i) |lw(.96i) |lw(.72i)
 357 .
 358 <math.h> type   DOMAIN  SING    OVERFLOW        UNDERFLOW       TLOSS
 359 _
 360 \fBerrno\fR     EDOM    EDOM    ERANGE  ERANGE  ERANGE
 361 _
 362 ACOS, ASIN\|(|x| > 1):  0.0     \(mi    \(mi    \(mi    \(mi
 363 _
 364 ATAN2\|(0,0):   0.0     \(mi    \(mi    \(mi    \(mi
 365 _
 366 COSH, SINH:     \(mi    \(mi    {\(+-HUGE_VAL}  \(mi    \(mi
 367 _
 368 EXP:    \(mi    \(mi    {+HUGE_VAL}     {0.0}   \(mi
 369 _
 370 FMOD\|(x,0):    {NaN}   \(mi    \(mi    \(mi    \(mi
 371 _
 372 HYPOT:  \(mi    \(mi    {+HUGE_VAL}     \(mi    \(mi
 373 _
 374 J0, J1, JN\|(|x| > X_TLOSS):    \(mi    \(mi    \(mi    \(mi    {0.0}
 375 _
 376 LGAMMA:
 377  usual cases    \(mi    \(mi    {+HUGE_VAL}     \(mi    \(mi
 378  (x = 0 or \(miinteger) \(mi    +HUGE_VAL       \(mi    \(mi    \(mi
 379 _
 380 LOG, LOG10:
 381  (x < 0)        \fB-HUGE_VAL\fR \(mi    \(mi    \(mi    \(mi
 382  (x = 0)        \(mi    \fB-HUGE_VAL\fR \(mi    \(mi    \(mi
 383 _
 384 POW:
 385  usual cases    \(mi    \(mi    \(+-HUGE_VAL    \(+-0.0 \(mi
 386  (x < 0) ** (y not an integer)  0.0     \(mi    \(mi    \(mi    \(mi
 387  0 ** 0 {1.0}   \(mi    \(mi    \(mi    \(mi
 388  0 ** (y < 0)   {\fB-HUGE_VAL\fR}       \(mi    \(mi    \(mi    \(mi
 389 _
 390 SQRT\|(x < 0):  0.0     \(mi    \(mi    \(mi    \(mi
 391 _
 392 Y0, Y1, YN:
 393  (x < 0)        {\fB-HUGE_VAL\fR}       \(mi    \(mi    \(mi    \(mi
 394  (x = 0)        \(mi    {\fB-HUGE_VAL\fR}       \(mi    \(mi    \(mi
 395  (x > X_TLOSS)  \(mi    \(mi    \(mi    \(mi    0.0
 396 .TE
 397
 398 .SS "Abbreviations"
 399 .sp
 400 .ne 2
 401 .mk
 402 .na
 403 \fB{...}\fR
 404 .ad
 405 .RS 12n
 406 .rt
 407 \fBerrno\fR is not to be relied upon in all braced cases.
 408 .RE
 409
 410 .sp
 411 .ne 2
 412 .mk
 413 .na
 414 \fBNaN\fR
 415 .ad
 416 .RS 12n
 417 .rt
 418 IEEE NaN result and invalid operation exception.
 419 .RE
 420
 421 .sp
 422 .ne 2
 423 .mk
 424 .na
 425 \fBHUGE_VAL\fR
 426 .ad
 427 .RS 12n
 428 .rt
 429 IEEE \(if result and division-by-zero exception.
 430 .RE
 431
 432 .sp
 433 .ne 2
 434 .mk
 435 .na
 436 \fBX_TLOSS\fR
 437 .ad
 438 .RS 12n
 439 .rt
 440 The value X_TLOSS is defined in <\fBvalues.h\fR>.
 441 .RE
 442
 443 .SH ANSI/ISO-C STANDARD CONFORMANCE
 444 .sp
 445 .LP
 446 The ANSI/ISO-C standard covers a small subset of the CAE specification.
 447 .sp
 448 .LP
 449 The following table summarizes the values returned in the exceptional cases.
 450 .SS "ANSI/ISO-C ERROR HANDLING PROCEDURES (compile with cc \fB-Xc\fR)"
 451 .sp
 452
 453 .sp
 454 .TS
 455 tab(    ) box;
 456 cw(1.1i) |cw(1.1i) |cw(1.1i) |cw(1.1i) |cw(1.11i)
 457 lw(1.1i) |lw(1.1i) |lw(1.1i) |lw(1.1i) |lw(1.11i)
 458 .
 459 <math.h> type   DOMAIN  SING    OVERFLOW        UNDERFLOW
 460 _
 461 \fBerrno\fR     EDOM    EDOM    ERANGE  ERANGE
 462 _
 463 ACOS, ASIN\|(|x| > 1):  0.0     \(mi    \(mi    \(mi
 464 _
 465 ATAN2\|(0,0):   0.0     \(mi    \(mi    \(mi
 466 _
 467 EXP:    \(mi    \(mi    +HUGE_VAL       0.0
 468 _
 469 FMOD\|(x,0):    NaN     \(mi    \(mi    \(mi
 470 _
 471 LOG, LOG10:
 472  (x < 0)        \fB-HUGE_VAL\fR \(mi    \(mi    \(mi
 473  (x = 0)        \(mi    \fB-HUGE_VAL\fR \(mi    \(mi
 474 _
 475 POW:
 476  usual cases    \(mi    \(mi    \(+-HUGE_VAL    \(+-0.0
 477  (x < 0) ** (y not an integer)  0.0     \(mi    \(mi    \(mi
 478  0 ** (y < 0)   \fB-HUGE_VAL\fR \(mi    \(mi    \(mi
 479 _
 480 SQRT\|(x < 0):  0.0     \(mi    \(mi    \(mi
 481 .TE
 482
 483 .SS "ABBREVIATIONS"
 484 .sp
 485 .ne 2
 486 .mk
 487 .na
 488 \fBNaN\fR
 489 .ad
 490 .RS 12n
 491 .rt
 492 IEEE NaN result and invalid operation exception.
 493 .RE
 494
 495 .sp
 496 .ne 2
 497 .mk
 498 .na
 499 \fBHUGE_VAL\fR
 500 .ad
 501 .RS 12n
 502 .rt
 503 IEEE \(if result and division-by-zero.
 504 .RE
 505
 506 .SH EXAMPLES
 507 .LP
 508 \fBExample 1 \fRExample of \fBmatherr()\fR function
 509 .sp
 510 .in +2
 511 .nf
 512 #include <stdio.h>
 513 #include <stdlib.h>
 514 #include <math.h>
 515
 516 int
 517 matherr(struct exception *x) {
 518     switch (x\(mi>type) {
 519         case DOMAIN:
 520             /* change sqrt to return sqrt(\(miarg1), not NaN */
 521    if (!strcmp(x\(mi>name, "sqrt")) {
 522     x\(mi>retval = sqrt(\(mix\(mi>arg1);
 523     return (0); /* print message and set errno */
 524    } /* FALLTHRU */
 525   case SING:
 526    /* all other domain or sing exceptions, print message and */
 527    /* abort */
 528    fprintf(stderr, "domain exception in %s\en", x\(mi>name);
 529    abort( );
 530    break;
 531   }
 532   return (0); /* all other exceptions, execute default procedure */
 533  }
 534 .fi
 535 .in -2
 536
 537 .SH ATTRIBUTES
 538 .sp
 539 .LP
 540 See \fBattributes\fR(5) for descriptions of the following attributes:
 541 .sp
 542
 543 .sp
 544 .TS
 545 tab(    ) box;
 546 cw(2.75i) |cw(2.75i)
 547 lw(2.75i) |lw(2.75i)
 548 .
 549 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 550 _
 551 MT-Level        MT-Safe
 552 .TE
 553
 554 .SH SEE ALSO
 555 .sp
 556 .LP
 557 \fBattributes\fR(5), \fBstandards\fR(5)