Movatterモバイル変換

NAME

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

SYNOPSIS

#include <math.h> double fma(doublex, doubley, doublez); float fmaf(floatx, floaty, floatz); long double fmal(long doublex, long doubley, long doublez);

DESCRIPTION

^[CX] The functionality described on this reference page is aligned with the ISO C standard. Any conflict between therequirements described here and the ISO C standard is unintentional. This volume of POSIX.1-2017 defers to the ISO Cstandard.
These functions shall compute (x * y) + z, rounded as one ternary operation: they shallcompute the value (as if) to infinite precision and round once to the result format, according to the rounding mode characterizedby the value of FLT_ROUNDS.
An application wishing to check for error situations should seterrno to zero and callfeclearexcept(FE_ALL_EXCEPT) before calling these functions. On return, iferrno is non-zero orfetestexcept(FE_INVALID | FE_DIVBYZERO | FE_OVERFLOW | FE_UNDERFLOW) is non-zero, an error has occurred.

RETURN VALUE

Upon successful completion, these functions shall return (x * y) +z, rounded as one ternaryoperation.
If the result overflows or underflows, a range error may occur.^[MX] On systems that support the IEC 60559 Floating-Point option,if the result overflows a range error shall occur.
Ifx ory are NaN, a NaN shall be returned.
Ifx multiplied byy is an exact infinity andz is also an infinity but with the opposite sign, a domainerror shall occur, and either a NaN (if supported), or an implementation-defined value shall be returned.
If one ofx andy is infinite, the other is zero, andz is not a NaN, a domain error shall occur, andeither a NaN (if supported), or an implementation-defined value shall be returned.
If one ofx andy is infinite, the other is zero, andz is a NaN, a NaN shall be returned and a domainerror may occur.
Ifx*y is not 0*Inf nor Inf*0 andz is a NaN, a NaN shall be returned.

ERRORS

These functions shall fail if:
Domain Error
^[MX]The value ofx*y+z is invalid, or the valuex*y is invalid andz is not a NaN.
If the integer expression (math_errhandling & MATH_ERRNO) is non-zero, thenerrno shall be set to [EDOM]. Ifthe integer expression (math_errhandling & MATH_ERREXCEPT) is non-zero, then the invalid floating-point exception shallbe raised.
Range Error
^[MX]The result overflows.
If the integer expression (math_errhandling & MATH_ERRNO) is non-zero, thenerrno shall be set to [ERANGE]. Ifthe integer expression (math_errhandling & MATH_ERREXCEPT) is non-zero, then the overflow floating-point exception shallbe raised.

These functions may fail if:
Domain Error
^[MX]The valuex*y is invalid andz is a NaN.
If the integer expression (math_errhandling & MATH_ERRNO) is non-zero, thenerrno shall be set to [EDOM]. Ifthe integer expression (math_errhandling & MATH_ERREXCEPT) is non-zero, then the invalid floating-point exception shallbe raised.
Range Error
The result underflows.
If the integer expression (math_errhandling & MATH_ERRNO) is non-zero, thenerrno shall be set to [ERANGE]. Ifthe integer expression (math_errhandling & MATH_ERREXCEPT) is non-zero, then the underflow floating-point exceptionshall be raised.
Range Error
The result overflows.
If the integer expression (math_errhandling & MATH_ERRNO) is non-zero, thenerrno shall be set to [ERANGE]. Ifthe integer expression (math_errhandling & MATH_ERREXCEPT) is non-zero, then the overflow floating-point exception shallbe raised.

The following sections are informative.

EXAMPLES

None.

APPLICATION USAGE

On error, the expressions (math_errhandling & MATH_ERRNO) and (math_errhandling & MATH_ERREXCEPT) areindependent of each other, but at least one of them must be non-zero.

RATIONALE

In many cases, clever use of floating (fused) multiply-add leads to much improved code; but its unexpected use by thecompiler can undermine carefully written code. The FP_CONTRACT macro can be used to disallow use of floating multiply-add; and thefma() function guarantees its use where desired. Many current machines provide hardware floating multiply-add instructions;software implementation can be used for others.