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
11

NAME

13       fma, fmaf, fmal — floating-point multiply-add
14

SYNOPSIS

16       #include <math.h>
17
18       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

DESCRIPTION

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
28       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
33       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

RETURN VALUE

40       Upon successful completion, these functions shall return  (x * y) +  z,
41       rounded as one ternary operation.
42
43       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
47       If x or y are NaN, a NaN shall be returned.
48
49       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
53       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
57       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
60       If x*y is not 0*Inf nor Inf*0 and z is a NaN, a NaN shall be returned.
61

ERRORS

63       These functions shall fail if:
64
65       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
69                   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
75       Range Error The result overflows.
76
77                   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
83       These functions may fail if:
84
85       Domain Error
86                   The value x*y is invalid and z is a NaN.
87
88                   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
94       Range Error The result underflows.
95
96                   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
102       Range Error The result overflows.
103
104                   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
110       The following sections are informative.
111

EXAMPLES

113       None.
114

APPLICATION USAGE

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

RATIONALE

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

FUTURE DIRECTIONS

130       None.
131

SEE ALSO

133       feclearexcept(), fetestexcept()
134
135       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
150       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 .
154
155
156
157IEEE/The Open Group                  2013                              FMA(3P)
Impressum