fma(3p) - c7

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

PROLOG

6       This  manual  page is part of the POSIX Programmer's Manual.  The Linux
7       implementation of this interface may differ (consult the  corresponding
8       Linux  manual page for details of Linux behavior), or the interface may
9       not be implemented on Linux.
10

NAME

12       fma, fmaf, fmal - floating-point multiply-add
13

SYNOPSIS

15       #include <math.h>
16
17       double fma(double x, double y, double z);
18       float fmaf(float x, float y, float z);
19       long double fmal(long double x, long double y, long double z);
20
21

DESCRIPTION

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

RETURN VALUE

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

ERRORS

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

EXAMPLES

96       None.
97

APPLICATION USAGE

99       On  error,  the  expressions  (math_errhandling   &   MATH_ERRNO)   and
100       (math_errhandling  & MATH_ERREXCEPT) are independent of each other, but
101       at least one of them must be non-zero.
102

RATIONALE

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

FUTURE DIRECTIONS

113       None.
114

COPYRIGHT

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