1FMA(P)                     POSIX Programmer's Manual                    FMA(P)
2
3
4

NAME

6       fma, fmaf, fmal - floating-point multiply-add
7

SYNOPSIS

9       #include <math.h>
10
11       double fma(double x, double y, double z);
12       float fmaf(float x, float y, float z);
13       long double fmal(long double x, long double y, long double z);
14
15

DESCRIPTION

17       These functions shall compute (x * y) + z, rounded as one ternary oper‐
18       ation: they shall compute the value (as if) to infinite  precision  and
19       round once to the result format, according to the rounding mode charac‐
20       terized by the value of FLT_ROUNDS.
21
22       An application wishing to check for error situations should  set  errno
23       to  zero  and  call  feclearexcept(FE_ALL_EXCEPT)  before calling these
24       functions.  On return, if errno is non-zero or  fetestexcept(FE_INVALID
25       |  FE_DIVBYZERO | FE_OVERFLOW | FE_UNDERFLOW) is non-zero, an error has
26       occurred.
27

RETURN VALUE

29       Upon successful completion, these functions shall return  (x * y) +  z,
30       rounded as one ternary operation.
31
32       If x or y are NaN, a NaN shall be returned.
33
34       If x multiplied by y is an exact infinity and z is also an infinity but
35       with the opposite sign, a domain error shall occur, and  either  a  NaN
36       (if supported), or an implementation-defined value shall be returned.
37
38       If one of x and y is infinite, the other is zero, and z is not a NaN, a
39       domain error shall occur, and either a NaN (if supported), or an imple‐
40       mentation-defined value shall be returned.
41
42       If one of x and y is infinite, the other is zero, and z is a NaN, a NaN
43       shall be returned and a domain error may occur.
44
45       If x* y is not 0*Inf nor Inf*0 and z is a NaN, a NaN shall be returned.
46

ERRORS

48       These functions shall fail if:
49
50       Domain Error
51              The value of x* y+ z is invalid, or the value x*  y  is  invalid
52              and z is not a NaN.
53
54       If  the integer expression (math_errhandling & MATH_ERRNO) is non-zero,
55       then  errno  shall  be  set  to  [EDOM].  If  the  integer   expression
56       (math_errhandling  &  MATH_ERREXCEPT)  is  non-zero,  then  the invalid
57       floating-point exception shall be raised.
58
59       Range Error
60              The result overflows.
61
62       If the integer expression (math_errhandling & MATH_ERRNO) is  non-zero,
63       then  errno  shall  be  set  to  [ERANGE].  If  the  integer expression
64       (math_errhandling & MATH_ERREXCEPT)  is  non-zero,  then  the  overflow
65       floating-point exception shall be raised.
66
67
68       These functions may fail if:
69
70       Domain Error
71              The value x* y is invalid and z is a NaN.
72
73       If  the integer expression (math_errhandling & MATH_ERRNO) is non-zero,
74       then  errno  shall  be  set  to  [EDOM].  If  the  integer   expression
75       (math_errhandling  &  MATH_ERREXCEPT)  is  non-zero,  then  the invalid
76       floating-point exception shall be raised.
77
78       Range Error
79              The result underflows.
80
81       If the integer expression (math_errhandling & MATH_ERRNO) is  non-zero,
82       then  errno  shall  be  set  to  [ERANGE].  If  the  integer expression
83       (math_errhandling & MATH_ERREXCEPT) is  non-zero,  then  the  underflow
84       floating-point exception shall be raised.
85
86
87       The following sections are informative.
88

EXAMPLES

90       None.
91

APPLICATION USAGE

93       On   error,   the   expressions  (math_errhandling  &  MATH_ERRNO)  and
94       (math_errhandling & MATH_ERREXCEPT) are independent of each other,  but
95       at least one of them must be non-zero.
96

RATIONALE

98       In  many  cases,  clever  use of floating (fused) multiply-add leads to
99       much improved code; but its unexpected use by the compiler  can  under‐
100       mine  carefully written code. The FP_CONTRACT macro can be used to dis‐
101       allow use of floating multiply-add; and the fma()  function  guarantees
102       its  use where desired. Many current machines provide hardware floating
103       multiply-add instructions; software implementation can be used for oth‐
104       ers.
105

FUTURE DIRECTIONS

107       None.
108

SEE ALSO

110       feclearexcept()  ,  fetestexcept()  ,  the  Base  Definitions volume of
111       IEEE Std 1003.1-2001, Section 4.18, Treatment of Error  Conditions  for
112       Mathematical Functions, <math.h>
113

115       Portions  of  this text are reprinted and reproduced in electronic form
116       from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
117       --  Portable  Operating  System  Interface (POSIX), The Open Group Base
118       Specifications Issue 6, Copyright (C) 2001-2003  by  the  Institute  of
119       Electrical  and  Electronics  Engineers, Inc and The Open Group. In the
120       event of any discrepancy between this version and the original IEEE and
121       The  Open Group Standard, the original IEEE and The Open Group Standard
122       is the referee document. The original Standard can be  obtained  online
123       at http://www.opengroup.org/unix/online.html .
124
125
126
127IEEE/The Open Group                  2003                               FMA(P)
Impressum