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