logo

oasis-root

Compiled tree of Oasis Linux based on own branch at <https://hacktivis.me/git/oasis/> git clone https://anongit.hacktivis.me/git/oasis-root.git

fma.3p (6196B)


  1. '\" et
  2. .TH FMA "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual"
  3. .\"
  4. .SH PROLOG
  5. This manual page is part of the POSIX Programmer's Manual.
  6. The Linux implementation of this interface may differ (consult
  7. the corresponding Linux manual page for details of Linux behavior),
  8. or the interface may not be implemented on Linux.
  9. .\"
  10. .SH NAME
  11. fma,
  12. fmaf,
  13. fmal
  14. \(em floating-point multiply-add
  15. .SH SYNOPSIS
  16. .LP
  17. .nf
  18. #include <math.h>
  19. .P
  20. double fma(double \fIx\fP, double \fIy\fP, double \fIz\fP);
  21. float fmaf(float \fIx\fP, float \fIy\fP, float \fIz\fP);
  22. long double fmal(long double \fIx\fP, long double \fIy\fP, long double \fIz\fP);
  23. .fi
  24. .SH DESCRIPTION
  25. The functionality described on this reference page is aligned with the
  26. ISO\ C standard. Any conflict between the requirements described here and the
  27. ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard.
  28. .P
  29. These functions shall compute (\fIx\fR\ *\ \fIy\fR)\ +\ \fIz\fR,
  30. rounded as one ternary operation: they shall compute the value (as if)
  31. to infinite precision and round once to the result format, according to
  32. the rounding mode characterized by the value of FLT_ROUNDS.
  33. .P
  34. An application wishing to check for error situations should set
  35. .IR errno
  36. to zero and call
  37. .IR feclearexcept (FE_ALL_EXCEPT)
  38. before calling these functions. On return, if
  39. .IR errno
  40. is non-zero or \fIfetestexcept\fR(FE_INVALID | FE_DIVBYZERO |
  41. FE_OVERFLOW | FE_UNDERFLOW) is non-zero, an error has occurred.
  42. .SH "RETURN VALUE"
  43. Upon successful completion, these functions shall return
  44. (\fIx\fR\ *\ \fIy\fR)\ + \fIz\fR, rounded as one ternary operation.
  45. .P
  46. If the result overflows or underflows, a range error may occur.
  47. On systems that support the IEC 60559 Floating-Point option, if the
  48. result overflows a range error shall occur.
  49. .P
  50. If
  51. .IR x
  52. or
  53. .IR y
  54. are NaN, a NaN shall be returned.
  55. .P
  56. If
  57. .IR x
  58. multiplied by
  59. .IR y
  60. is an exact infinity and
  61. .IR z
  62. is also an infinity but with the opposite sign, a domain error shall
  63. occur, and either a NaN (if supported), or an implementation-defined
  64. value shall be returned.
  65. .P
  66. If one of
  67. .IR x
  68. and
  69. .IR y
  70. is infinite, the other is zero, and
  71. .IR z
  72. is not a NaN, a domain error shall occur, and either a NaN (if
  73. supported), or an implementation-defined value shall be returned.
  74. .P
  75. If one of
  76. .IR x
  77. and
  78. .IR y
  79. is infinite, the other is zero, and
  80. .IR z
  81. is a NaN, a NaN shall be returned and a domain error may occur.
  82. .P
  83. If
  84. .IR x *\c
  85. .IR y
  86. is not 0*Inf nor Inf*0 and
  87. .IR z
  88. is a NaN, a NaN shall be returned.
  89. .SH ERRORS
  90. These functions shall fail if:
  91. .IP "Domain\ Error" 12
  92. The value of
  93. .IR x *\c
  94. .IR y +\c
  95. .IR z
  96. is invalid, or the value
  97. .IR x *\c
  98. .IR y
  99. is invalid and
  100. .IR z
  101. is not a NaN.
  102. .RS 12
  103. .P
  104. If the integer expression (\fImath_errhandling\fR & MATH_ERRNO) is
  105. non-zero, then
  106. .IR errno
  107. shall be set to
  108. .BR [EDOM] .
  109. If the integer expression (\fImath_errhandling\fR & MATH_ERREXCEPT) is
  110. non-zero, then the invalid floating-point exception shall be raised.
  111. .RE
  112. .IP "Range\ Error" 12
  113. The result overflows.
  114. .RS 12
  115. .P
  116. If the integer expression (\fImath_errhandling\fR & MATH_ERRNO) is
  117. non-zero, then
  118. .IR errno
  119. shall be set to
  120. .BR [ERANGE] .
  121. If the integer expression (\fImath_errhandling\fR & MATH_ERREXCEPT) is
  122. non-zero, then the overflow floating-point exception shall be raised.
  123. .RE
  124. .br
  125. .P
  126. These functions may fail if:
  127. .IP "Domain\ Error" 12
  128. The value
  129. .IR x *\c
  130. .IR y
  131. is invalid and
  132. .IR z
  133. is a NaN.
  134. .RS 12
  135. .P
  136. If the integer expression (\fImath_errhandling\fR & MATH_ERRNO) is
  137. non-zero, then
  138. .IR errno
  139. shall be set to
  140. .BR [EDOM] .
  141. If the integer expression (\fImath_errhandling\fR & MATH_ERREXCEPT) is
  142. non-zero, then the invalid floating-point exception shall be raised.
  143. .RE
  144. .IP "Range\ Error" 12
  145. The result underflows.
  146. .RS 12
  147. .P
  148. If the integer expression (\fImath_errhandling\fR & MATH_ERRNO) is
  149. non-zero, then
  150. .IR errno
  151. shall be set to
  152. .BR [ERANGE] .
  153. If the integer expression (\fImath_errhandling\fR & MATH_ERREXCEPT) is
  154. non-zero, then the underflow floating-point exception shall be raised.
  155. .RE
  156. .IP "Range\ Error" 12
  157. The result overflows.
  158. .RS 12
  159. .P
  160. If the integer expression (\fImath_errhandling\fR & MATH_ERRNO) is
  161. non-zero, then
  162. .IR errno
  163. shall be set to
  164. .BR [ERANGE] .
  165. If the integer expression (\fImath_errhandling\fR & MATH_ERREXCEPT) is
  166. non-zero, then the overflow floating-point exception shall be raised.
  167. .RE
  168. .LP
  169. .IR "The following sections are informative."
  170. .SH EXAMPLES
  171. None.
  172. .SH "APPLICATION USAGE"
  173. On error, the expressions (\fImath_errhandling\fR & MATH_ERRNO) and
  174. (\fImath_errhandling\fR & MATH_ERREXCEPT) are independent of each
  175. other, but at least one of them must be non-zero.
  176. .SH RATIONALE
  177. In many cases, clever use of floating (\fIfused\fR) multiply-add leads
  178. to much improved code; but its unexpected use by the compiler can
  179. undermine carefully written code. The FP_CONTRACT macro can be used to
  180. disallow use of floating multiply-add; and the
  181. \fIfma\fR()
  182. function guarantees its use where desired. Many current machines
  183. provide hardware floating multiply-add instructions; software
  184. implementation can be used for others.
  185. .SH "FUTURE DIRECTIONS"
  186. None.
  187. .SH "SEE ALSO"
  188. .IR "\fIfeclearexcept\fR\^(\|)",
  189. .IR "\fIfetestexcept\fR\^(\|)"
  190. .P
  191. The Base Definitions volume of POSIX.1\(hy2017,
  192. .IR "Section 4.20" ", " "Treatment of Error Conditions for Mathematical Functions",
  193. .IR "\fB<math.h>\fP"
  194. .\"
  195. .SH COPYRIGHT
  196. Portions of this text are reprinted and reproduced in electronic form
  197. from IEEE Std 1003.1-2017, Standard for Information Technology
  198. -- Portable Operating System Interface (POSIX), The Open Group Base
  199. Specifications Issue 7, 2018 Edition,
  200. Copyright (C) 2018 by the Institute of
  201. Electrical and Electronics Engineers, Inc and The Open Group.
  202. In the event of any discrepancy between this version and the original IEEE and
  203. The Open Group Standard, the original IEEE and The Open Group Standard
  204. is the referee document. The original Standard can be obtained online at
  205. http://www.opengroup.org/unix/online.html .
  206. .PP
  207. Any typographical or formatting errors that appear
  208. in this page are most likely
  209. to have been introduced during the conversion of the source files to
  210. man page format. To report such errors, see
  211. https://www.kernel.org/doc/man-pages/reporting_bugs.html .