man3/fma.3

   1 .\" Copyright 2002 Walter Harms (walter.harms@informatik.uni-oldenburg.de)
   2 .\" and Copyright 2008, Linux Foundation, written by Michael Kerrisk
   3 .\"     <mtk.manpages@gmail.com>
   4 .\"
   5 .\" SPDX-License-Identifier: GPL-1.0-or-later
   6 .\"
   7 .\" Modified 2004-11-15, Added further text on FLT_ROUNDS
   8 .\"     as suggested by AEB and Fabian Kreutz
   9 .\"
  10 .TH FMA 3 2021-03-22 "Linux man-pages (unreleased)"
  11 .SH NAME
  12 fma, fmaf, fmal \- floating-point multiply and add
  13 .SH LIBRARY
  14 Math library
  15 .RI ( libm ", " \-lm )
  16 .SH SYNOPSIS
  17 .nf
  18 .B #include <math.h>
  19 .PP
  20 .BI "double fma(double " x ", double " y ", double " z );
  21 .BI "float fmaf(float " x ", float " y ", float " z );
  22 .BI "long double fmal(long double " x ", long double " y ", long double " z );
  23 .fi
  24 .PP
  25 .RS -4
  26 Feature Test Macro Requirements for glibc (see
  27 .BR feature_test_macros (7)):
  28 .RE
  29 .PP
  30 .BR fma (),
  31 .BR fmaf (),
  32 .BR fmal ():
  33 .nf
  34     _ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L
  35 .fi
  36 .SH DESCRIPTION
  37 These functions compute
  38 .IR x " * " y " + " z .
  39 The result is rounded as one ternary operation according to the
  40 current rounding mode (see
  41 .BR fenv (3)).
  42 .SH RETURN VALUE
  43 These functions return the value of
  44 .IR x " * " y " + " z ,
  45 rounded as one ternary operation.
  46 .PP
  47 If
  48 .I x
  49 or
  50 .I y
  51 is a NaN, a NaN is returned.
  52 .PP
  53 If
  54 .I x
  55 times
  56 .I y
  57 is an exact infinity, and
  58 .I z
  59 is an infinity with the opposite sign,
  60 a domain error occurs,
  61 and a NaN is returned.
  62 .PP
  63 .\" POSIX.1-2008 allows some possible differences for the following two
  64 .\" domain error cases, but on Linux they are treated the same (AFAICS).
  65 .\" Nevertheless, we'll mirror POSIX.1 and describe the two cases
  66 .\" separately.
  67 If one of
  68 .I x
  69 or
  70 .I y
  71 is an infinity, the other is 0, and
  72 .I z
  73 is not a NaN,
  74 a domain error occurs, and
  75 a NaN is returned.
  76 .\" POSIX.1 says that a NaN or an implementation-defined value shall
  77 .\" be returned for this case.
  78 .PP
  79 If one of
  80 .I x
  81 or
  82 .I y
  83 is an infinity, and the other is 0, and
  84 .I z
  85 is a NaN,
  86 .\" POSIX.1 makes the domain error optional for this case.
  87 a domain error occurs, and
  88 a NaN is returned.
  89 .PP
  90 If
  91 .I x
  92 times
  93 .I y
  94 is not an infinity times zero (or vice versa), and
  95 .I z
  96 is a NaN,
  97 a NaN is returned.
  98 .PP
  99 If the result overflows,
 100 a range error occurs, and
 101 an infinity with the correct sign is returned.
 102 .PP
 103 If the result underflows,
 104 a range error occurs, and
 105 a signed 0 is returned.
 106 .SH ERRORS
 107 See
 108 .BR math_error (7)
 109 for information on how to determine whether an error has occurred
 110 when calling these functions.
 111 .PP
 112 The following errors can occur:
 113 .TP
 114 Domain error: \fIx\fP * \fIy\fP + \fIz\fP, \
 115 or \fIx\fP * \fIy\fP is invalid and \fIz\fP is not a NaN
 116 .\" .I errno
 117 .\" is set to
 118 .\" .BR EDOM .
 119 An invalid floating-point exception
 120 .RB ( FE_INVALID )
 121 is raised.
 122 .TP
 123 Range error: result overflow
 124 .\" .I errno
 125 .\" is set to
 126 .\" .BR ERANGE .
 127 An overflow floating-point exception
 128 .RB ( FE_OVERFLOW )
 129 is raised.
 130 .TP
 131 Range error: result underflow
 132 .\" .I errno
 133 .\" is set to
 134 .\" .BR ERANGE .
 135 An underflow floating-point exception
 136 .RB ( FE_UNDERFLOW )
 137 is raised.
 138 .PP
 139 These functions do not set
 140 .IR errno .
 141 .\" FIXME . Is it intentional that these functions do not set errno?
 142 .\" Bug raised: http://sources.redhat.com/bugzilla/show_bug.cgi?id=6801
 143 .SH VERSIONS
 144 These functions first appeared in glibc in version 2.1.
 145 .SH ATTRIBUTES
 146 For an explanation of the terms used in this section, see
 147 .BR attributes (7).
 148 .ad l
 149 .nh
 150 .TS
 151 allbox;
 152 lbx lb lb
 153 l l l.
 154 Interface       Attribute       Value
 155 T{
 156 .BR fma (),
 157 .BR fmaf (),
 158 .BR fmal ()
 159 T}      Thread safety   MT-Safe
 160 .TE
 161 .hy
 162 .ad
 163 .sp 1
 164 .SH STANDARDS
 165 C99, POSIX.1-2001, POSIX.1-2008.
 166 .SH SEE ALSO
 167 .BR remainder (3),
 168 .BR remquo (3)