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