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

atan2.3p (5653B)

    

  1. '\" et
  2. .TH ATAN2 "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. atan2,
  12. atan2f,
  13. atan2l
  14. \(em arc tangent functions
  15. .SH SYNOPSIS
  16. .LP
  17. .nf
  18. #include <math.h>
  19. .P
  20. double atan2(double \fIy\fP, double \fIx\fP);
  21. float atan2f(float \fIy\fP, float \fIx\fP);
  22. long double atan2l(long double \fIy\fP, long double \fIx\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 the principal value of the arc tangent of
  30. .IR y /\c
  31. .IR x ,
  32. using the signs of both arguments to determine the quadrant of the
  33. return value.
  34. .P
  35. An application wishing to check for error situations should set
  36. .IR errno
  37. to zero and call
  38. .IR feclearexcept (FE_ALL_EXCEPT)
  39. before calling these functions. On return, if
  40. .IR errno
  41. is non-zero or \fIfetestexcept\fR(FE_INVALID | FE_DIVBYZERO |
  42. FE_OVERFLOW | FE_UNDERFLOW) is non-zero, an error has occurred.
  43. .SH "RETURN VALUE"
  44. Upon successful completion, these functions shall return the arc
  45. tangent of
  46. .IR y /\c
  47. .IR x
  48. in the range [\-\(*p,\(*p] radians.
  49. .P
  50. If
  51. .IR y
  52. is \(+-0 and
  53. .IR x
  54. is < 0, \(+-\(*p shall be returned.
  55. .P
  56. If
  57. .IR y
  58. is \(+-0 and
  59. .IR x
  60. is > 0, \(+-0 shall be returned.
  61. .P
  62. If
  63. .IR y
  64. is < 0 and
  65. .IR x
  66. is \(+-0, \-\(*p/2 shall be returned.
  67. .P
  68. If
  69. .IR y
  70. is > 0 and
  71. .IR x
  72. is \(+-0, \(*p/2 shall be returned.
  73. .P
  74. If
  75. .IR x
  76. is 0, a pole error shall not occur.
  77. .P
  78. If either
  79. .IR x
  80. or
  81. .IR y
  82. is NaN, a NaN shall be returned.
  83. .P
  84. If the correct value would cause underflow, a range error may occur, and
  85. \fIatan\fR(),
  86. \fIatan2f\fR(),
  87. and
  88. \fIatan2l\fR()
  89. shall return an implementation-defined value no greater in magnitude
  90. than DBL_MIN, FLT_MIN, and LDBL_MIN, respectively.
  91. .P
  92. If the IEC 60559 Floating-Point option is supported,
  93. .IR y /\c
  94. .IR x
  95. should be returned.
  96. .P
  97. If
  98. .IR y
  99. is \(+-0 and
  100. .IR x
  101. is \-0, \(+-\(*p shall be returned.
  102. .P
  103. If
  104. .IR y
  105. is \(+-0 and
  106. .IR x
  107. is +0, \(+-0 shall be returned.
  108. .P
  109. For finite values of \(+-\c
  110. .IR y
  111. > 0, if
  112. .IR x
  113. is \-Inf, \(+-\(*p shall be returned.
  114. .P
  115. For finite values of \(+-\c
  116. .IR y
  117. > 0, if
  118. .IR x
  119. is +Inf, \(+-0 shall be returned.
  120. .P
  121. For finite values of
  122. .IR x ,
  123. if
  124. .IR y
  125. is \(+-Inf, \(+-\(*p/2 shall be returned.
  126. .P
  127. If
  128. .IR y
  129. is \(+-Inf and
  130. .IR x
  131. is \-Inf, \(+-3\(*p/4 shall be returned.
  132. .P
  133. If
  134. .IR y
  135. is \(+-Inf and
  136. .IR x
  137. is +Inf, \(+-\(*p/4 shall be returned.
  138. .P
  139. If both arguments are 0, a domain error shall not occur.
  140. .SH ERRORS
  141. These functions may fail if:
  142. .IP "Range\ Error" 12
  143. The result underflows.
  144. .RS 12 
  145. .P
  146. If the integer expression (\fImath_errhandling\fR & MATH_ERRNO) is
  147. non-zero, then
  148. .IR errno
  149. shall be set to
  150. .BR [ERANGE] .
  151. If the integer expression (\fImath_errhandling\fR & MATH_ERREXCEPT) is
  152. non-zero, then the underflow floating-point exception shall be raised.
  153. .RE
  154. .LP
  155. .IR "The following sections are informative."
  156. .SH EXAMPLES
  157. .SS "Converting Cartesian to Polar Coordinates System"
  158. .P
  159. The function below uses
  160. \fIatan2\fR()
  161. to convert a 2d vector expressed in cartesian coordinates
  162. (\fIx\fR,\fIy\fR) to the polar coordinates (\fIrho\fR,\fItheta\fR).
  163. There are other ways to compute the angle
  164. .IR theta ,
  165. using
  166. \fIasin\fR()
  167. \fIacos\fR(),
  168. or
  169. \fIatan\fR().
  170. However,
  171. \fIatan2\fR()
  172. presents here two advantages:
  173. .IP " *" 4
  174. The angle's quadrant is automatically determined.
  175. .IP " *" 4
  176. The singular cases (0,\fIy\fR) are taken into account.
  177. .P
  178. Finally, this example uses
  179. \fIhypot\fR()
  180. rather than
  181. \fIsqrt\fR()
  182. since it is better for special cases; see
  183. \fIhypot\fR()
  184. for more information.
  185. .sp
  186. .RS 4
  187. .nf
  189. #include <math.h>
  190. .P
  191. void
  192. cartesian_to_polar(const double x, const double y,
  193.                    double *rho, double *theta
  194.     )
  195. {
  196.     *rho   = hypot (x,y); /* better than sqrt(x*x+y*y) */
  197.     *theta = atan2 (y,x);
  198. }
  199. .fi
  200. .P
  201. .RE
  202. .SH "APPLICATION USAGE"
  203. On error, the expressions (\fImath_errhandling\fR & MATH_ERRNO) and
  204. (\fImath_errhandling\fR & MATH_ERREXCEPT) are independent of each
  205. other, but at least one of them must be non-zero.
  206. .SH RATIONALE
  207. None.
  208. .SH "FUTURE DIRECTIONS"
  209. None.
  210. .SH "SEE ALSO"
  211. .IR "\fIacos\fR\^(\|)",
  212. .IR "\fIasin\fR\^(\|)",
  213. .IR "\fIatan\fR\^(\|)",
  214. .IR "\fIfeclearexcept\fR\^(\|)",
  215. .IR "\fIfetestexcept\fR\^(\|)",
  216. .IR "\fIhypot\fR\^(\|)",
  217. .IR "\fIisnan\fR\^(\|)",
  218. .IR "\fIsqrt\fR\^(\|)",
  219. .IR "\fItan\fR\^(\|)"
  220. .P
  221. The Base Definitions volume of POSIX.1\(hy2017,
  222. .IR "Section 4.20" ", " "Treatment of Error Conditions for Mathematical Functions",
  223. .IR "\fB<math.h>\fP"
  224. .\"
  225. .SH COPYRIGHT
  226. Portions of this text are reprinted and reproduced in electronic form
  227. from IEEE Std 1003.1-2017, Standard for Information Technology
  228. -- Portable Operating System Interface (POSIX), The Open Group Base
  229. Specifications Issue 7, 2018 Edition,
  230. Copyright (C) 2018 by the Institute of
  231. Electrical and Electronics Engineers, Inc and The Open Group.
  232. In the event of any discrepancy between this version and the original IEEE and
  233. The Open Group Standard, the original IEEE and The Open Group Standard
  234. is the referee document. The original Standard can be obtained online at
  235. http://www.opengroup.org/unix/online.html .
  236. .PP
  237. Any typographical or formatting errors that appear
  238. in this page are most likely
  239. to have been introduced during the conversion of the source files to
  240. man page format. To report such errors, see
  241. https://www.kernel.org/doc/man-pages/reporting_bugs.html .