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  2017-09-15 "" "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 .in -4n
  27 Feature Test Macro Requirements for glibc (see
  28 .BR feature_test_macros (7)):
  29 .in
  30 .PP
  31 .ad l
  32 .BR fma (),
  33 .BR fmaf (),
  34 .BR fmal ():
  35 .RS 4
  36 _ISOC99_SOURCE || _POSIX_C_SOURCE\ >=\ 200112L
  37 .RE
  38 .ad
  39 .SH DESCRIPTION
  40 These functions compute
  41 .IR x " * " y " + " z .
  42 The result is rounded as one ternary operation according to the
  43 current rounding mode (see
  44 .BR fenv (3)).
  45 .SH RETURN VALUE
  46 These functions return the value of
  47 .IR x " * " y " + " z ,
  48 rounded as one ternary operation.
  49 .PP
  50 If
  51 .I x
  52 or
  53 .I y
  54 is a NaN, a NaN is returned.
  55 .PP
  56 If
  57 .I x
  58 times
  59 .I y
  60 is an exact infinity, and
  61 .I z
  62 is an infinity with the opposite sign,
  63 a domain error occurs,
  64 and a NaN is returned.
  65 .PP
  66 .\" POSIX.1-2008 allows some possible differences for the following two
  67 .\" domain error cases, but on Linux they are treated the same (AFAICS).
  68 .\" Nevertheless, we'll mirror POSIX.1 and describe the two cases
  69 .\" separately.
  70 If one of
  71 .I x
  72 or
  73 .I y
  74 is an infinity, the other is 0, and
  75 .I z
  76 is not a NaN,
  77 a domain error occurs, and
  78 a NaN is returned.
  79 .\" POSIX.1 says that a NaN or an implementation-defined value shall
  80 .\" be returned for this case.
  81 .PP
  82 If one of
  83 .I x
  84 or
  85 .I y
  86 is an infinity, and the other is 0, and
  87 .I z
  88 is a NaN,
  89 .\" POSIX.1 makes the domain error optional for this case.
  90 a domain error occurs, and
  91 a NaN is returned.
  92 .PP
  93 If
  94 .I x
  95 times
  96 .I y
  97 is not an infinity times zero (or vice versa), and
  98 .I z
  99 is a NaN,
 100 a NaN is returned.
 101 .PP
 102 If the result overflows,
 103 a range error occurs, and
 104 an infinity with the correct sign is returned.
 105 .PP
 106 If the result underflows,
 107 a range error occurs, and
 108 a signed 0 is returned.
 109 .SH ERRORS
 110 See
 111 .BR math_error (7)
 112 for information on how to determine whether an error has occurred
 113 when calling these functions.
 114 .PP
 115 The following errors can occur:
 116 .TP
 117 Domain error: \fIx\fP * \fIy\fP + \fIz\fP, \
 118 or \fIx\fP * \fIy\fP is invalid and \fIz\fP is not a NaN
 119 .\" .I errno
 120 .\" is set to
 121 .\" .BR EDOM .
 122 An invalid floating-point exception
 123 .RB ( FE_INVALID )
 124 is raised.
 125 .TP
 126 Range error: result overflow
 127 .\" .I errno
 128 .\" is set to
 129 .\" .BR ERANGE .
 130 An overflow floating-point exception
 131 .RB ( FE_OVERFLOW )
 132 is raised.
 133 .TP
 134 Range error: result underflow
 135 .\" .I errno
 136 .\" is set to
 137 .\" .BR ERANGE .
 138 An underflow floating-point exception
 139 .RB ( FE_UNDERFLOW )
 140 is raised.
 141 .PP
 142 These functions do not set
 143 .IR errno .
 144 .\" FIXME . Is it intentional that these functions do not set errno?
 145 .\" Bug raised: http://sources.redhat.com/bugzilla/show_bug.cgi?id=6801
 146 .SH VERSIONS
 147 These functions first appeared in glibc in version 2.1.
 148 .SH ATTRIBUTES
 149 For an explanation of the terms used in this section, see
 150 .BR attributes (7).
 151 .TS
 152 allbox;
 153 lbw21 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 .SH CONFORMING TO
 163 C99, POSIX.1-2001, POSIX.1-2008.
 164 .SH SEE ALSO
 165 .BR remainder (3),
 166 .BR remquo (3)