.\" Copyright (c) 1991 The Regents of the University of California. | |

.\" All rights reserved. | |

.\" | |

.\" Redistribution and use in source and binary forms, with or without | |

.\" modification, are permitted provided that the following conditions | |

.\" are met: | |

.\" 1. Redistributions of source code must retain the above copyright | |

.\" notice, this list of conditions and the following disclaimer. | |

.\" 2. Redistributions in binary form must reproduce the above copyright | |

.\" notice, this list of conditions and the following disclaimer in the | |

.\" documentation and/or other materials provided with the distribution. | |

.\" 3. All advertising materials mentioning features or use of this software | |

.\" must display the following acknowledgement: | |

.\" This product includes software developed by the University of | |

.\" California, Berkeley and its contributors. | |

.\" 4. Neither the name of the University nor the names of its contributors | |

.\" may be used to endorse or promote products derived from this software | |

.\" without specific prior written permission. | |

.\" | |

.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND | |

.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE | |

.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE | |

.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE | |

.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL | |

.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS | |

.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) | |

.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT | |

.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY | |

.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF | |

.\" SUCH DAMAGE. | |

.\" | |

.\" from: @(#)atan2.3 5.1 (Berkeley) 5/2/91 | |

.\" $FreeBSD: src/lib/msun/man/atan2.3,v 1.14 2005/01/28 21:13:34 ru Exp $ | |

.\" | |

.Dd January 14, 2005 | |

.Dt ATAN2 3 | |

.Os | |

.Sh NAME | |

.Nm atan2 , | |

.Nm atan2f | |

.Nd arc tangent functions of two variables | |

.Sh LIBRARY | |

.Lb libm | |

.Sh SYNOPSIS | |

.In math.h | |

.Ft double | |

.Fn atan2 "double y" "double x" | |

.Ft float | |

.Fn atan2f "float y" "float x" | |

.Sh DESCRIPTION | |

The | |

.Fn atan2 | |

and the | |

.Fn atan2f | |

functions compute the principal value of the arc tangent of | |

.Fa y/ Ns Ar x , | |

using the signs of both arguments to determine the quadrant of | |

the return value. | |

.Sh RETURN VALUES | |

The | |

.Fn atan2 | |

and the | |

.Fn atan2f | |

functions, if successful, | |

return the arc tangent of | |

.Fa y/ Ns Ar x | |

in the range | |

.Bk -words | |

.Bq \&- Ns \*(Pi , \&+ Ns \*(Pi | |

.Ek | |

radians. | |

Here are some of the special cases: | |

.Bl -column atan_(y,x)_:=____ sign(y)_(Pi_atan2(Xy_xX))___ | |

.It Fn atan2 y x No := Ta | |

.Fn atan y/x Ta | |

if | |

.Ar x | |

> 0, | |

.It Ta sign( Ns Ar y Ns )*(\*(Pi - | |

.Fn atan "\\*(Bay/x\\*(Ba" ) Ta | |

if | |

.Ar x | |

< 0, | |

.It Ta | |

.No 0 Ta | |

if x = y = 0, or | |

.It Ta | |

.Pf sign( Ar y Ns )*\\*(Pi/2 Ta | |

if | |

.Ar x | |

= 0 \(!= | |

.Ar y . | |

.El | |

.Sh NOTES | |

The function | |

.Fn atan2 | |

defines "if x > 0," | |

.Fn atan2 0 0 | |

= 0 despite that previously | |

.Fn atan2 0 0 | |

may have generated an error message. | |

The reasons for assigning a value to | |

.Fn atan2 0 0 | |

are these: | |

.Bl -enum -offset indent | |

.It | |

Programs that test arguments to avoid computing | |

.Fn atan2 0 0 | |

must be indifferent to its value. | |

Programs that require it to be invalid are vulnerable | |

to diverse reactions to that invalidity on diverse computer systems. | |

.It | |

The | |

.Fn atan2 | |

function is used mostly to convert from rectangular (x,y) | |

to polar | |

.if n\ | |

(r,theta) | |

.if t\ | |

(r,\(*h) | |

coordinates that must satisfy x = | |

.if n\ | |

r\(**cos theta | |

.if t\ | |

r\(**cos\(*h | |

and y = | |

.if n\ | |

r\(**sin theta. | |

.if t\ | |

r\(**sin\(*h. | |

These equations are satisfied when (x=0,y=0) | |

is mapped to | |

.if n \ | |

(r=0,theta=0). | |

.if t \ | |

(r=0,\(*h=0). | |

In general, conversions to polar coordinates | |

should be computed thus: | |

.Bd -unfilled -offset indent | |

.if n \{\ | |

r := hypot(x,y); ... := sqrt(x\(**x+y\(**y) | |

theta := atan2(y,x). | |

.\} | |

.if t \{\ | |

r := hypot(x,y); ... := \(sr(x\u\s82\s10\d+y\u\s82\s10\d) | |

\(*h := atan2(y,x). | |

.\} | |

.Ed | |

.It | |

The foregoing formulas need not be altered to cope in a | |

reasonable way with signed zeros and infinities | |

on a machine that conforms to | |

.Tn IEEE 754 ; | |

the versions of | |

.Xr hypot 3 | |

and | |

.Fn atan2 | |

provided for | |

such a machine are designed to handle all cases. | |

That is why | |

.Fn atan2 \(+-0 \-0 | |

= \(+-\*(Pi | |

for instance. | |

In general the formulas above are equivalent to these: | |

.Bd -unfilled -offset indent | |

.if n \ | |

r := sqrt(x\(**x+y\(**y); if r = 0 then x := copysign(1,x); | |

.if t \ | |

r := \(sr(x\(**x+y\(**y);\0\0if r = 0 then x := copysign(1,x); | |

.Ed | |

.El | |

.Sh SEE ALSO | |

.Xr acos 3 , | |

.Xr asin 3 , | |

.Xr atan 3 , | |

.Xr cos 3 , | |

.Xr cosh 3 , | |

.Xr math 3 , | |

.Xr sin 3 , | |

.Xr sinh 3 , | |

.Xr tan 3 , | |

.Xr tanh 3 | |

.Sh STANDARDS | |

The | |

.Fn atan2 | |

function conforms to | |

.St -isoC . |