doc/html/ref/math-library-compatibility-modes.html

   1 <!-- Copyright (C) 2003 Red Hat, Inc.                                -->
   2 <!-- This material may be distributed only subject to the terms      -->
   3 <!-- and conditions set forth in the Open Publication License, v1.0  -->
   4 <!-- or later (the latest version is presently available at          -->
   5 <!-- http://www.opencontent.org/openpub/).                           -->
   6 <!-- Distribution of the work or derivative of the work in any       -->
   7 <!-- standard (paper) book form is prohibited unless prior           -->
   8 <!-- permission is obtained from the copyright holder.               -->
   9 <HTML
  10 ><HEAD
  11 ><TITLE
  12 >Math library compatibility modes</TITLE
  13 ><meta name="MSSmartTagsPreventParsing" content="TRUE">
  14 <META
  15 NAME="GENERATOR"
  16 CONTENT="Modular DocBook HTML Stylesheet Version 1.76b+
  17 "><LINK
  18 REL="HOME"
  19 TITLE="eCos Reference Manual"
  20 HREF="ecos-ref.html"><LINK
  21 REL="UP"
  22 TITLE="C and math library overview"
  23 HREF="c-and-math-library-overview.html"><LINK
  24 REL="PREVIOUS"
  25 TITLE="C and math library overview"
  26 HREF="c-and-math-library-overview.html"><LINK
  27 REL="NEXT"
  28 TITLE="Some implementation details"
  29 HREF="libc-implementation-details.html"></HEAD
  30 ><BODY
  31 CLASS="SECT1"
  32 BGCOLOR="#FFFFFF"
  33 TEXT="#000000"
  34 LINK="#0000FF"
  35 VLINK="#840084"
  36 ALINK="#0000FF"
  37 ><DIV
  38 CLASS="NAVHEADER"
  39 ><TABLE
  40 SUMMARY="Header navigation table"
  41 WIDTH="100%"
  42 BORDER="0"
  43 CELLPADDING="0"
  44 CELLSPACING="0"
  45 ><TR
  46 ><TH
  47 COLSPAN="3"
  48 ALIGN="center"
  49 >eCos Reference Manual</TH
  50 ></TR
  51 ><TR
  52 ><TD
  53 WIDTH="10%"
  54 ALIGN="left"
  55 VALIGN="bottom"
  56 ><A
  57 HREF="c-and-math-library-overview.html"
  58 ACCESSKEY="P"
  59 >Prev</A
  60 ></TD
  61 ><TD
  62 WIDTH="80%"
  63 ALIGN="center"
  64 VALIGN="bottom"
  65 >Chapter 13. C and math library overview</TD
  66 ><TD
  67 WIDTH="10%"
  68 ALIGN="right"
  69 VALIGN="bottom"
  70 ><A
  71 HREF="libc-implementation-details.html"
  72 ACCESSKEY="N"
  73 >Next</A
  74 ></TD
  75 ></TR
  76 ></TABLE
  77 ><HR
  78 ALIGN="LEFT"
  79 WIDTH="100%"></DIV
  80 ><DIV
  81 CLASS="SECT1"
  82 ><H1
  83 CLASS="SECT1"
  84 ><A
  85 NAME="MATH-LIBRARY-COMPATIBILITY-MODES">Math library compatibility modes</H1
  86 ><P
  87 >This math library is capable of being operated in several
  88 different compatibility modes. These options deal solely with how
  89 errors are handled. </P
  90 ><P
  91 >There are 4 compatibility modes: ANSI/POSIX 1003.1;
  92 IEEE-754; X/Open Portability Guide issue 3 (XPG3); and
  93 System V Interface Definition Edition 3. </P
  94 ><P
  95 >In IEEE mode, the <TT
  96 CLASS="FUNCTION"
  97 >matherr()</TT
  98 > function
  99 (see below) is never called, no warning messages are printed on
 100 the stderr output stream, and errno is never set. </P
 101 ><P
 102 >In ANSI/POSIX mode, errno is set correctly,
 103 but <TT
 104 CLASS="FUNCTION"
 105 >matherr()</TT
 106 > is never called and no warning messages
 107 are printed on the stderr output stream. </P
 108 ><P
 109 >In X/Open mode, errno is set correctly,
 110 <TT
 111 CLASS="FUNCTION"
 112 >matherr()</TT
 113 > is called, but no warning messages are printed
 114 on the stderr output stream. </P
 115 ><P
 116 >In SVID mode, functions which overflow return
 117 a value HUGE (defined in <TT
 118 CLASS="FILENAME"
 119 >math.h</TT
 120 >), which is the maximum
 121 single precision floating point value (as opposed to
 122 HUGE_VAL which is meant to stand for infinity). errno is
 123 set correctly and <TT
 124 CLASS="FUNCTION"
 125 >matherr()</TT
 126 > is called. If
 127 <TT
 128 CLASS="FUNCTION"
 129 >matherr()</TT
 130 > returns 0, warning messages are printed on
 131 the stderr output stream for some errors. </P
 132 ><P
 133 >The mode can be compiled-in as IEEE-only, or any one of the
 134 above methods settable at run-time. </P
 135 ><DIV
 136 CLASS="NOTE"
 137 ><BLOCKQUOTE
 138 CLASS="NOTE"
 139 ><P
 140 ><B
 141 >Note: </B
 142 >This math library assumes that the hardware (or software floating
 143 point emulation) supports IEEE-754 style arithmetic, 32-bit 2's
 144 complement integer arithmetic, doubles are in 64-bit IEEE-754 format.</P
 145 ></BLOCKQUOTE
 146 ></DIV
 147 ><DIV
 148 CLASS="SECT2"
 149 ><H2
 150 CLASS="SECT2"
 151 ><A
 152 NAME="AEN10153">matherr()</H2
 153 ><P
 154 >As mentioned above, in X/Open or SVID modes, the user
 155             can supply a function <TT
 156 CLASS="FUNCTION"
 157 >matherr()</TT
 158 > of
 159             the form:</P
 160 ><TABLE
 161 BORDER="5"
 162 BGCOLOR="#E0E0F0"
 163 WIDTH="70%"
 164 ><TR
 165 ><TD
 166 ><PRE
 167 CLASS="PROGRAMLISTING"
 168 >int <TT
 169 CLASS="FUNCTION"
 170 >matherr</TT
 171 >( struct exception *e )</PRE
 172 ></TD
 173 ></TR
 174 ></TABLE
 175 ><P
 176 >where struct exception is defined as:</P
 177 ><TABLE
 178 BORDER="5"
 179 BGCOLOR="#E0E0F0"
 180 WIDTH="70%"
 181 ><TR
 182 ><TD
 183 ><PRE
 184 CLASS="PROGRAMLISTING"
 185 >struct exception {
 186  int type;
 187  char *name;
 188  double arg1, arg2, retval;
 189 }; </PRE
 190 ></TD
 191 ></TR
 192 ></TABLE
 193 ><P
 194 >type is the exception type and is one of:</P
 195 ><P
 196 ></P
 197 ><DIV
 198 CLASS="VARIABLELIST"
 199 ><DL
 200 ><DT
 201 >DOMAIN</DT
 202 ><DD
 203 ><P
 204 >argument domain exception</P
 205 ></DD
 206 ><DT
 207 >SING</DT
 208 ><DD
 209 ><P
 210 >argument singularity</P
 211 ></DD
 212 ><DT
 213 >OVERFLOW</DT
 214 ><DD
 215 ><P
 216 >overflow range exception</P
 217 ></DD
 218 ><DT
 219 >UNDERFLOW</DT
 220 ><DD
 221 ><P
 222 >underflow range exception</P
 223 ></DD
 224 ><DT
 225 >TLOSS</DT
 226 ><DD
 227 ><P
 228 >total loss of significance</P
 229 ></DD
 230 ><DT
 231 >PLOSS</DT
 232 ><DD
 233 ><P
 234 >partial loss of significance</P
 235 ></DD
 236 ></DL
 237 ></DIV
 238 ><P
 239 ><TT
 240 CLASS="PARAMETER"
 241 ><I
 242 >name</I
 243 ></TT
 244 > is a string containing the name of the
 245 function</P
 246 ><P
 247 ><TT
 248 CLASS="PARAMETER"
 249 ><I
 250 >arg1</I
 251 ></TT
 252 > and <TT
 253 CLASS="PARAMETER"
 254 ><I
 255 >arg2</I
 256 ></TT
 257 > are the
 258 arguments passed to the function</P
 259 ><P
 260 ><TT
 261 CLASS="PARAMETER"
 262 ><I
 263 >retval</I
 264 ></TT
 265 > is the default value that will be returned
 266 by the function, and can be changed by <TT
 267 CLASS="FUNCTION"
 268 >matherr()</TT
 269 ></P
 270 ><DIV
 271 CLASS="NOTE"
 272 ><BLOCKQUOTE
 273 CLASS="NOTE"
 274 ><P
 275 ><B
 276 >Note: </B
 277 >matherr must have &#8220;C&#8221; linkage, not &#8220;C&#0043;&#0043;&#8221; linkage.</P
 278 ></BLOCKQUOTE
 279 ></DIV
 280 ><P
 281 >If matherr returns zero, or the user doesn't supply
 282 their own matherr, then the following <SPAN
 283 CLASS="emphasis"
 284 ><I
 285 CLASS="EMPHASIS"
 286 >usually</I
 287 ></SPAN
 288 > happens
 289 in SVID mode:</P
 290 ><DIV
 291 CLASS="TABLE"
 292 ><A
 293 NAME="AEN10199"><P
 294 ><B
 295 >Table 13-1. Behavior of math exception handling</B
 296 ></P
 297 ><TABLE
 298 BORDER="1"
 299 CLASS="CALSTABLE"
 300 ><THEAD
 301 ><TR
 302 ><TH
 303 ALIGN="LEFT"
 304 VALIGN="TOP"
 305 >Type</TH
 306 ><TH
 307 ALIGN="LEFT"
 308 VALIGN="TOP"
 309 >Behavior</TH
 310 ></TR
 311 ></THEAD
 312 ><TBODY
 313 ><TR
 314 ><TD
 315 ALIGN="LEFT"
 316 VALIGN="TOP"
 317 >DOMAIN</TD
 318 ><TD
 319 ALIGN="LEFT"
 320 VALIGN="TOP"
 321 >0.0 returned,
 322 errno=EDOM, and a message printed on stderr</TD
 323 ></TR
 324 ><TR
 325 ><TD
 326 ALIGN="LEFT"
 327 VALIGN="TOP"
 328 >SING</TD
 329 ><TD
 330 ALIGN="LEFT"
 331 VALIGN="TOP"
 332 >HUGE of appropriate
 333 sign is returned, errno=EDOM, and a message is printed
 334 on stderr</TD
 335 ></TR
 336 ><TR
 337 ><TD
 338 ALIGN="LEFT"
 339 VALIGN="TOP"
 340 >OVERFLOW</TD
 341 ><TD
 342 ALIGN="LEFT"
 343 VALIGN="TOP"
 344 >HUGE of
 345 appropriate sign is returned, and errno=ERANGE</TD
 346 ></TR
 347 ><TR
 348 ><TD
 349 ALIGN="LEFT"
 350 VALIGN="TOP"
 351 >UNDERFLOW</TD
 352 ><TD
 353 ALIGN="LEFT"
 354 VALIGN="TOP"
 355 >0.0 is
 356 returned and errno=ERANGE</TD
 357 ></TR
 358 ><TR
 359 ><TD
 360 ALIGN="LEFT"
 361 VALIGN="TOP"
 362 >TLOSS</TD
 363 ><TD
 364 ALIGN="LEFT"
 365 VALIGN="TOP"
 366 >0.0 is returned,
 367 errno=ERANGE, and a message is printed on stderr</TD
 368 ></TR
 369 ><TR
 370 ><TD
 371 ALIGN="LEFT"
 372 VALIGN="TOP"
 373 >PLOSS</TD
 374 ><TD
 375 ALIGN="LEFT"
 376 VALIGN="TOP"
 377 >The current
 378 implementation doesn't return this type</TD
 379 ></TR
 380 ></TBODY
 381 ></TABLE
 382 ></DIV
 383 ><P
 384 >X/Open mode is similar except that the message is
 385 not printed on stderr and HUGE_VAL is used in place of
 386 HUGE</P
 387 ></DIV
 388 ><DIV
 389 CLASS="SECT2"
 390 ><H2
 391 CLASS="SECT2"
 392 ><A
 393 NAME="AEN10226">Thread-safety and re-entrancy</H2
 394 ><P
 395 >With the appropriate configuration options set below, the
 396 math library is fully thread-safe if:</P
 397 ><P
 398 ></P
 399 ><UL
 400 ><LI
 401 ><P
 402 >Depending on the compatibility mode, the
 403                 setting of the errno variable from the C library is
 404                 thread-safe</P
 405 ></LI
 406 ><LI
 407 ><P
 408 >Depending on the compatibility mode, sending error messages
 409 to the stderr output stream using the C library
 410 <TT
 411 CLASS="FUNCTION"
 412 >fputs()</TT
 413 >
 414  function is thread-safe </P
 415 ></LI
 416 ><LI
 417 ><P
 418 >Depending on the compatibility mode, the user-supplied
 419 <TT
 420 CLASS="FUNCTION"
 421 >matherr()</TT
 422 >
 423  function and anything it depends on are thread-safe </P
 424 ></LI
 425 ></UL
 426 ><P
 427 >In addition, with the exception of the <TT
 428 CLASS="FUNCTION"
 429 >gamma*()</TT
 430 > and <TT
 431 CLASS="FUNCTION"
 432 >lgamma*()</TT
 433 > functions,
 434 the math library is reentrant (and thus safe to use from interrupt handlers)
 435 if the Math library is always in IEEE mode.</P
 436 ></DIV
 437 ></DIV
 438 ><DIV
 439 CLASS="NAVFOOTER"
 440 ><HR
 441 ALIGN="LEFT"
 442 WIDTH="100%"><TABLE
 443 SUMMARY="Footer navigation table"
 444 WIDTH="100%"
 445 BORDER="0"
 446 CELLPADDING="0"
 447 CELLSPACING="0"
 448 ><TR
 449 ><TD
 450 WIDTH="33%"
 451 ALIGN="left"
 452 VALIGN="top"
 453 ><A
 454 HREF="c-and-math-library-overview.html"
 455 ACCESSKEY="P"
 456 >Prev</A
 457 ></TD
 458 ><TD
 459 WIDTH="34%"
 460 ALIGN="center"
 461 VALIGN="top"
 462 ><A
 463 HREF="ecos-ref.html"
 464 ACCESSKEY="H"
 465 >Home</A
 466 ></TD
 467 ><TD
 468 WIDTH="33%"
 469 ALIGN="right"
 470 VALIGN="top"
 471 ><A
 472 HREF="libc-implementation-details.html"
 473 ACCESSKEY="N"
 474 >Next</A
 475 ></TD
 476 ></TR
 477 ><TR
 478 ><TD
 479 WIDTH="33%"
 480 ALIGN="left"
 481 VALIGN="top"
 482 >C and math library overview</TD
 483 ><TD
 484 WIDTH="34%"
 485 ALIGN="center"
 486 VALIGN="top"
 487 ><A
 488 HREF="c-and-math-library-overview.html"
 489 ACCESSKEY="U"
 490 >Up</A
 491 ></TD
 492 ><TD
 493 WIDTH="33%"
 494 ALIGN="right"
 495 VALIGN="top"
 496 >Some implementation details</TD
 497 ></TR
 498 ></TABLE
 499 ></DIV
 500 ></BODY
 501 ></HTML
 502 >