1.\" $NetBSD: fma.3,v 1.3 2017/09/27 10:12:47 maya Exp $ 2.\" Copyright (c) 2005 David Schultz <das@FreeBSD.org> 3.\" All rights reserved. 4.\" 5.\" Redistribution and use in source and binary forms, with or without 6.\" modification, are permitted provided that the following conditions 7.\" are met: 8.\" 1. Redistributions of source code must retain the above copyright 9.\" notice, this list of conditions and the following disclaimer. 10.\" 2. Redistributions in binary form must reproduce the above copyright 11.\" notice, this list of conditions and the following disclaimer in the 12.\" documentation and/or other materials provided with the distribution. 13.\" 14.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 15.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 16.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 17.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 18.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 19.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 20.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 21.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 22.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 23.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 24.\" SUCH DAMAGE. 25.\" 26.\" $FreeBSD: head/lib/msun/man/fma.3 152755 2005-11-24 09:25:10Z joel $ 27.\" 28.Dd September 27, 2017 29.Dt FMA 3 30.Os 31.Sh NAME 32.Nm fma , 33.Nm fmaf , 34.Nm fmal 35.Nd fused multiply-add 36.Sh LIBRARY 37.Lb libm 38.Sh SYNOPSIS 39.In math.h 40.Ft double 41.Fn fma "double x" "double y" "double z" 42.Ft float 43.Fn fmaf "float x" "float y" "float z" 44.Ft long double 45.Fn fmal "long double x" "long double y" "long double z" 46.Sh DESCRIPTION 47The 48.Fn fma , 49.Fn fmaf , 50and 51.Fn fmal 52functions return 53.No "(x * y) + z" , 54computed with only one rounding error. 55Using the ordinary multiplication and addition operators, by contrast, 56results in two roundings: one for the intermediate product and one for 57the final result. 58.Pp 59For instance, the expression 60.No "1.2e100 * 2.0e208 - 1.4e308" 61produces \*(If due to overflow in the intermediate product, whereas 62.No "fma(1.2e100, 2.0e208, -1.4e308)" 63returns approximately 1.0e308. 64.Pp 65The fused multiply-add operation is often used to improve the 66accuracy of calculations such as dot products. 67It may also be used to improve performance on machines that implement 68it natively. 69The macros 70.Dv FP_FAST_FMA , 71.Dv FP_FAST_FMAF 72and 73.Dv FP_FAST_FMAL 74may be defined in 75.In math.h 76to indicate that 77.Fn fma , 78.Fn fmaf , 79and 80.Fn fmal 81(respectively) have comparable or faster speed than a multiply 82operation followed by an add operation. 83.Sh IMPLEMENTATION NOTES 84In general, these routines will behave as one would expect if 85.No "x * y + z" 86were computed with unbounded precision and range, 87then rounded to the precision of the return type. 88However, on some platforms, if 89.Fa z 90is \*(Na, these functions may not raise an exception even 91when the computation of 92.No "x * y" 93would have otherwise generated an invalid exception. 94.Sh SEE ALSO 95.Xr fenv 3 , 96.Xr math 3 97.Sh STANDARDS 98The 99.Fn fma , 100.Fn fmaf , 101and 102.Fn fmal 103functions conform to 104.St -isoC-99 . 105A fused multiply-add operation with virtually identical 106characteristics appears in IEEE draft standard 754R. 107.Sh HISTORY 108The 109.Fn fma 110and 111.Fn fmaf 112routines first appeared in 113.Fx 5.4 , 114and 115.Fn fmal 116appeared in 117.Fx 6.0 . 118The 119.Fn fma , 120.Fn fmaf 121and 122.Fn fmal 123routines were imported into 124.Nx 125in 126.Nx 7.0 . 127