MATH-FP(2)                                             MATH-FP(2)

     NAME
          math-fp - floating point

     SYNOPSIS
          include   "math.m";
          math := load Math Math->PATH;

          Infinity, NaN, MachEps, Pi, Degree: real;
          INVAL, ZDIV, OVFL, UNFL, INEX: int;
          RND_NR, RND_NINF, RND_PINF, RND_Z, RND_MASK: int;

          getFPcontrol, getFPstatus: fn():  int;
          FPcontrol, FPstatus: fn(r, mask: int): int;
          ilogb: fn(x: real): int;
          scalbn: fn(x: real, n: int): real;
          copysign: fn(x, s: real): real;
          finite, isnan: fn(x: real): int;
          nextafter: fn(x, y: real): real;

          fdim, fmin, fmax: fn(x, y: real): real;
          fabs: fn(x: real): real;
          ceil, floor: fn(x: real): real;
          remainder: fn(x, p: real): real;
          fmod: fn(x, y: real): real;
          modf: fn(x: real): (int,real);
          rint: fn(x: real): real;

     DESCRIPTION
          These constants and functions provide control over rounding
          modes, exceptions, and other properties of floating point
          arithmetic.

          Infinity and NaN are constants containing the positive
          infinity and quiet not-a-number values of the IEEE binary
          floating point standard, double precision.  MachEps is 2-52,
          the smallest e such that 1+e is not equal to 1.  Pi is the
          nearest machine number to the infinitely precise value.
          Degree is Pi/180.

          Each thread has a floating point control word (governing
          rounding mode and whether a particular floating point excep-
          tion causes a trap) and a floating point status word (stor-
          ing accumulated exception flags).  The functions FPcontrol
          and FPstatus copy bits to the control or status word, in
          positions specified by a mask, returning the previous values
          of the bits specified in the mask.  The functions
          getFPcontrol and getFPstatus return the words unchanged.

          INVAL, ZDIV, OVFL, UNFL, and INEX are non-overlapping
          single-bit masks used to compose arguments or return values.

     Page 1                       Plan 9             (printed 4/19/21)

     MATH-FP(2)                                             MATH-FP(2)

          They stand for the five IEEE exceptions: `invalid operation'
          (0/0,0+NaN,Infinity-Infinity,sqrt(-1)), `division by zero'
          (1/0), `overflow' (1.8e308), `underflow' (1.1e-308), and
          `inexact' (.3*.3).

          RND_NR, RND_NINF, RND_PINF, and RND_Z are distinct bit pat-
          terns for `round to nearest even', `round toward negative
          infinity', `round toward infinity', and `round toward 0',
          any of which can be set or extracted from the floating point
          control word using RND_MASK.  For example, FPcontrol(0,
          UNFL) makes underflow silent; FPstatus(0, INEX) checks and
          clears the inexact flag; and FPcontrol(RND_PINF, RND_MASK)
          sets directed rounding.

          By default, INEX is quiet, OVFL, UNFL, and ZDIV are fatal,
          and rounding is to nearest even.  Limbo modules are entitled
          to assume this, and if they wish to use quiet underflow,
          overflow, or zero-divide, they must either set and restore
          the control register or clearly document that their caller
          must do so.

          The ilogb function returns the nearest integral logarithm
          base 2 of the absolute value of x: for positive finite x, 1
          _< x*2-ilogb(x) < 2, and ilogb(-x) = ilogb(x).  Scalbn(x,n)
          is a scaled power of two: x*2n.  Copysign(x,s) has the mag-
          nitude of x and the sign bit of s. Nextafter(x,y) is the
          machine number nearest x closer to y.  Finally, finite(x) is
          0 if x is Nan or Infinity, 1 otherwise, and isnan(x) is 1 if
          x is Nan and 0 otherwise.

          The function fdim(x,y) = x-y if x is greater than y, other-
          wise it is 0.  The functions fmin, fmax, fabs, ceil, and
          floor are the customary minimum, maximum, absolute value,
          and integer rounding routines.

          There are two functions for computing the modulus: fmod(x,y)
          is the function defined by the C standard which gives the
          value x-i*y for some i such that the remainder has the sign
          of x and magnitude less than the magnitude of y, while
          remainder(x,y) is the function defined by the IEEE standard
          which gives a remainder of magnitude no more than half the
          magnitude of y. The function modf(x) breaks x into integer
          and fractional parts returned in a tuple, and rint rounds to
          an integer, following the rounding mode specified in the
          floating point control word.

     SOURCE
          /libinterp/math.c

     SEE ALSO
          math-intro(2)

     Page 2                       Plan 9             (printed 4/19/21)