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