1FMA(3P) POSIX Programmer's Manual FMA(3P)
2
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
13 fma, fmaf, fmal — floating-point multiply-add
14
16 #include <math.h>
17 double fma(double x, double y, double z);
19 float fmaf(float x, float y, float z);
20 long double fmal(long double x, long double y, long double z);
21
23 The functionality described on this reference page is aligned with the
24 ISO C standard. Any conflict between the requirements described here
25 and the ISO C standard is unintentional. This volume of POSIX.1‐2008
26 defers to the ISO C standard.
27 These functions shall compute (x * y) + z, rounded as one ternary oper‐
29 ation: they shall compute the value (as if) to infinite precision and
30 round once to the result format, according to the rounding mode charac‐
31 terized by the value of FLT_ROUNDS.
32 An application wishing to check for error situations should set errno
34 to zero and call feclearexcept(FE_ALL_EXCEPT) before calling these
35 functions. On return, if errno is non-zero or fetestexcept(FE_INVALID |
36 FE_DIVBYZERO | FE_OVERFLOW | FE_UNDERFLOW) is non-zero, an error has
37 occurred.
38
40 Upon successful completion, these functions shall return (x * y) + z,
41 rounded as one ternary operation.
42 If the result overflows or underflows, a range error may occur. On
44 systems that support the IEC 60559 Floating-Point option, if the result
45 overflows a range error shall occur.
46 If x or y are NaN, a NaN shall be returned.
48 If x multiplied by y is an exact infinity and z is also an infinity but
50 with the opposite sign, a domain error shall occur, and either a NaN
51 (if supported), or an implementation-defined value shall be returned.
52 If one of x and y is infinite, the other is zero, and z is not a NaN, a
54 domain error shall occur, and either a NaN (if supported), or an imple‐
55 mentation-defined value shall be returned.
56 If one of x and y is infinite, the other is zero, and z is a NaN, a NaN
58 shall be returned and a domain error may occur.
59 If x*y is not 0*Inf nor Inf*0 and z is a NaN, a NaN shall be returned.
61
63 These functions shall fail if:
64 Domain Error
66 The value of x*y+z is invalid, or the value x*y is invalid
67 and z is not a NaN.
68 If the integer expression (math_errhandling & MATH_ERRNO)
70 is non-zero, then errno shall be set to [EDOM]. If the
71 integer expression (math_errhandling & MATH_ERREXCEPT) is
72 non-zero, then the invalid floating-point exception shall
73 be raised.
74 Range Error The result overflows.
76 If the integer expression (math_errhandling & MATH_ERRNO)
78 is non-zero, then errno shall be set to [ERANGE]. If the
79 integer expression (math_errhandling & MATH_ERREXCEPT) is
80 non-zero, then the overflow floating-point exception shall
81 be raised.
82 These functions may fail if:
84 Domain Error
86 The value x*y is invalid and z is a NaN.
87 If the integer expression (math_errhandling & MATH_ERRNO)
89 is non-zero, then errno shall be set to [EDOM]. If the
90 integer expression (math_errhandling & MATH_ERREXCEPT) is
91 non-zero, then the invalid floating-point exception shall
92 be raised.
93 Range Error The result underflows.
95 If the integer expression (math_errhandling & MATH_ERRNO)
97 is non-zero, then errno shall be set to [ERANGE]. If the
98 integer expression (math_errhandling & MATH_ERREXCEPT) is
99 non-zero, then the underflow floating-point exception shall
100 be raised.
101 Range Error The result overflows.
103 If the integer expression (math_errhandling & MATH_ERRNO)
105 is non-zero, then errno shall be set to [ERANGE]. If the
106 integer expression (math_errhandling & MATH_ERREXCEPT) is
107 non-zero, then the overflow floating-point exception shall
108 be raised.
109 The following sections are informative.
111
113 None.
114
116 On error, the expressions (math_errhandling & MATH_ERRNO) and
117 (math_errhandling & MATH_ERREXCEPT) are independent of each other, but
118 at least one of them must be non-zero.
119
121 In many cases, clever use of floating (fused) multiply-add leads to
122 much improved code; but its unexpected use by the compiler can under‐
123 mine carefully written code. The FP_CONTRACT macro can be used to dis‐
124 allow use of floating multiply-add; and the fma() function guarantees
125 its use where desired. Many current machines provide hardware floating
126 multiply-add instructions; software implementation can be used for oth‐
127 ers.
128
130 None.
131
133 feclearexcept(), fetestexcept()
134 The Base Definitions volume of POSIX.1‐2008, Section 4.19, Treatment of
136 Error Conditions for Mathematical Functions, <math.h>
137
139 Portions of this text are reprinted and reproduced in electronic form
140 from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology
141 -- Portable Operating System Interface (POSIX), The Open Group Base
142 Specifications Issue 7, Copyright (C) 2013 by the Institute of Electri‐
143 cal and Electronics Engineers, Inc and The Open Group. (This is
144 POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the
145 event of any discrepancy between this version and the original IEEE and
146 The Open Group Standard, the original IEEE and The Open Group Standard
147 is the referee document. The original Standard can be obtained online
148 at http://www.unix.org/online.html .
149 Any typographical or formatting errors that appear in this page are
151 most likely to have been introduced during the conversion of the source
152 files to man page format. To report such errors, see https://www.ker‐
153 nel.org/doc/man-pages/reporting_bugs.html .
154IEEE/The Open Group 2013 FMA(3P)