original/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  2013-09-17 "" "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 The
  47 .BR fma ()
  48 function computes
  49 .IR x " * " y " + " z .
  50 The result is rounded as one ternary operation according to the
  51 current rounding mode (see
  52 .BR fenv (3)).
  53 .SH RETURN VALUE
  54 These functions return the value of
  55 .IR x " * " y " + " z ,
  56 rounded as one ternary operation.
  57
  58 If
  59 .I x
  60 or
  61 .I y
  62 is a NaN, a NaN is returned.
  63
  64 If
  65 .I x
  66 times
  67 .I y
  68 is an exact infinity, and
  69 .I z
  70 is an infinity with the opposite sign,
  71 a domain error occurs,
  72 and a NaN is returned.
  73
  74 .\" POSIX.1-2008 allows some possible differences for the following two
  75 .\" domain error cases, but on Linux they are treated the same (AFAICS).
  76 .\" Nevertheless, we'll mirror POSIX.1 and describe the two cases
  77 .\" separately.
  78 If one of
  79 .I x
  80 or
  81 .I y
  82 is an infinity, the other is 0, and
  83 .I z
  84 is not a NaN,
  85 a domain error occurs, and
  86 a NaN is returned.
  87 .\" POSIX.1 says that a NaN or an implementation-defined value shall
  88 .\" be returned for this case.
  89
  90 If one of
  91 .I x
  92 or
  93 .I y
  94 is an infinity, and the other is 0, and
  95 .I z
  96 is a NaN,
  97 .\" POSIX.1 makes the domain error optional for this case.
  98 a domain error occurs, and
  99 a NaN is returned.
 100
 101 If
 102 .I x
 103 times
 104 .I y
 105 is not an infinity times zero (or vice versa), and
 106 .I z
 107 is a NaN,
 108 a NaN is returned.
 109
 110 If the result overflows,
 111 a range error occurs, and
 112 an infinity with the correct sign is returned.
 113
 114 If the result underflows,
 115 a range error occurs, and
 116 a signed 0 is returned.
 117 .SH ERRORS
 118 See
 119 .BR math_error (7)
 120 for information on how to determine whether an error has occurred
 121 when calling these functions.
 122 .PP
 123 The following errors can occur:
 124 .TP
 125 Domain error: \fIx\fP * \fIy\fP + \fIz\fP, \
 126 or \fIx\fP * \fIy\fP is invalid and \fIz\fP is not a NaN
 127 .\" .I errno
 128 .\" is set to
 129 .\" .BR EDOM .
 130 An invalid floating-point exception
 131 .RB ( FE_INVALID )
 132 is raised.
 133 .TP
 134 Range error: result overflow
 135 .\" .I errno
 136 .\" is set to
 137 .\" .BR ERANGE .
 138 An overflow floating-point exception
 139 .RB ( FE_OVERFLOW )
 140 is raised.
 141 .TP
 142 Range error: result underflow
 143 .\" .I errno
 144 .\" is set to
 145 .\" .BR ERANGE .
 146 An underflow floating-point exception
 147 .RB ( FE_UNDERFLOW )
 148 is raised.
 149 .PP
 150 These functions do not set
 151 .IR errno .
 152 .\" FIXME . Is it intentional that these functions do not set errno?
 153 .\" Bug raised: http://sources.redhat.com/bugzilla/show_bug.cgi?id=6801
 154 .SH VERSIONS
 155 These functions first appeared in glibc in version 2.1.
 156 .SH ATTRIBUTES
 157 .SS Multithreading (see pthreads(7))
 158 The
 159 .BR fma (),
 160 .BR fmaf (),
 161 and
 162 .BR fmal ()
 163 functions are thread-safe.
 164 .SH CONFORMING TO
 165 C99, POSIX.1-2001.
 166 .SH SEE ALSO
 167 .BR remainder (3),
 168 .BR remquo (3)
 169 .SH COLOPHON
 170 This page is part of release 3.79 of the Linux
 171 .I man-pages
 172 project.
 173 A description of the project,
 174 information about reporting bugs,
 175 and the latest version of this page,
 176 can be found at
 177 \%http://www.kernel.org/doc/man\-pages/.