FMA(3)                     POSIX Programmer's Manual                    FMA(3)



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

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

SYNOPSIS
       #include <math.h>

       double fma(double _x, double _y, double _z);
       float fmaf(float _x, float _y, float _z);
       long double fmal(long double _x, long double _y, long double _z);

DESCRIPTION
       The functionality described on this reference page is aligned with the
       ISO C standard. Any conflict between the requirements described here
       and the ISO C standard is unintentional. This volume of POSIX.1-2017
       defers to the ISO C standard.

       These functions shall compute (_x * _y) + _z, rounded as one ternary
       operation: they shall compute the value (as if) to infinite precision
       and round once to the result format, according to the rounding mode
       characterized by the value of FLT_ROUNDS.

       An application wishing to check for error situations should set errno
       to zero and call feclearexcept(FE_ALL_EXCEPT) before calling these
       functions. On return, if errno is non-zero or fetestexcept(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 ternary operation.

       If the result overflows or underflows, a range error may occur.  On
       systems that support the IEC 60559 Floating-Point option, if the result
       overflows a range error shall occur.

       If _x or _y are NaN, a NaN shall be returned.

       If _x multiplied by _y is an exact infinity and _z is also an infinity but
       with the opposite sign, a domain error shall occur, and either a NaN
       (if supported), or an implementation-defined value shall be returned.

       If one of _x and _y is infinite, the other is zero, and _z is not a NaN, a
       domain error shall occur, and either a NaN (if supported), or an
       implementation-defined value shall be returned.

       If one of _x and _y is infinite, the other is zero, and _z is a NaN, a NaN
       shall be returned and a domain error may occur.

       If _x*_y is not 0*Inf nor Inf*0 and _z is a NaN, a NaN shall be returned.

ERRORS
       These functions shall fail if:

       Domain Error
                   The value of _x*_y+_z is invalid, or the value _x*_y is invalid
                   and _z is not a NaN.

                   If the integer expression (math__errhandling & MATH_ERRNO)
                   is non-zero, then errno shall be set to [EDOM].  If the
                   integer expression (math__errhandling & MATH_ERREXCEPT) is
                   non-zero, then the invalid floating-point exception shall
                   be raised.

       Range Error The result overflows.

                   If the integer expression (math__errhandling & MATH_ERRNO)
                   is non-zero, then errno shall be set to [ERANGE].  If the
                   integer expression (math__errhandling & MATH_ERREXCEPT) is
                   non-zero, then the overflow floating-point exception shall
                   be raised.

       These functions may fail if:

       Domain Error
                   The value _x*_y is invalid and _z is a NaN.

                   If the integer expression (math__errhandling & MATH_ERRNO)
                   is non-zero, then errno shall be set to [EDOM].  If the
                   integer expression (math__errhandling & MATH_ERREXCEPT) is
                   non-zero, then the invalid floating-point exception shall
                   be raised.

       Range Error The result underflows.

                   If the integer expression (math__errhandling & MATH_ERRNO)
                   is non-zero, then errno shall be set to [ERANGE].  If the
                   integer expression (math__errhandling & MATH_ERREXCEPT) is
                   non-zero, then the underflow floating-point exception shall
                   be raised.

       Range Error The result overflows.

                   If the integer expression (math__errhandling & MATH_ERRNO)
                   is non-zero, then errno shall be set to [ERANGE].  If the
                   integer expression (math__errhandling & MATH_ERREXCEPT) is
                   non-zero, then the overflow floating-point exception shall
                   be raised.

       The following sections are informative.

EXAMPLES
       None.

APPLICATION USAGE
       On error, the expressions (math__errhandling & MATH_ERRNO) and
       (math__errhandling & MATH_ERREXCEPT) are independent 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 the compiler can
       undermine carefully written code. The FP_CONTRACT macro can be used to
       disallow use of floating multiply-add; and the fma() function
       guarantees its use where desired. Many current machines provide
       hardware floating multiply-add instructions; software implementation
       can be used for others.

FUTURE DIRECTIONS
       None.

SEE ALSO
       feclearexcept(), fetestexcept()

       The Base Definitions volume of POSIX.1-2017, Section 4.20, Treatment of
       Error Conditions for Mathematical Functions, <math.h>

COPYRIGHT
       Portions of this text are reprinted and reproduced in electronic form
       from IEEE Std 1003.1-2017, Standard for Information Technology --
       Portable Operating System Interface (POSIX), The Open Group Base
       Specifications Issue 7, 2018 Edition, Copyright (C) 2018 by the
       Institute of Electrical and Electronics Engineers, Inc and The Open
       Group.  In the event of any discrepancy between this version and the
       original IEEE and The Open Group Standard, the original IEEE and The
       Open Group Standard is the referee document. The original Standard can
       be obtained online at http://www.opengroup.org/unix/online.html .

       Any typographical or formatting errors that appear in this page are
       most likely to have been introduced during the conversion of the source
       files to man page format. To report such errors, see
       https://www.kernel.org/doc/man-pages/reporting_bugs.html .



IEEE/The Open Group                  2017                               FMA(3)
