lib/msun/man/atan2.3

   1 .\" Copyright (c) 1991 The Regents of the University of California.
   2 .\" All rights reserved.
   3 .\"
   4 .\" Redistribution and use in source and binary forms, with or without
   5 .\" modification, are permitted provided that the following conditions
   6 .\" are met:
   7 .\" 1. Redistributions of source code must retain the above copyright
   8 .\"    notice, this list of conditions and the following disclaimer.
   9 .\" 2. Redistributions in binary form must reproduce the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer in the
  11 .\"    documentation and/or other materials provided with the distribution.
  12 .\" 4. Neither the name of the University nor the names of its contributors
  13 .\"    may be used to endorse or promote products derived from this software
  14 .\"    without specific prior written permission.
  15 .\"
  16 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  17 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  18 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  19 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  20 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  21 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  22 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  23 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  24 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  25 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  26 .\" SUCH DAMAGE.
  27 .\"
  28 .\"     from: @(#)atan2.3       5.1 (Berkeley) 5/2/91
  29 .\" $FreeBSD$
  30 .\"
  31 .Dd January 14, 2005
  32 .Dt ATAN2 3
  33 .Os
  34 .Sh NAME
  35 .Nm atan2 ,
  36 .Nm atan2f
  37 .Nd arc tangent functions of two variables
  38 .Sh LIBRARY
  39 .Lb libm
  40 .Sh SYNOPSIS
  41 .In math.h
  42 .Ft double
  43 .Fn atan2 "double y" "double x"
  44 .Ft float
  45 .Fn atan2f "float y" "float x"
  46 .Sh DESCRIPTION
  47 The
  48 .Fn atan2
  49 and the
  50 .Fn atan2f
  51 functions compute the principal value of the arc tangent of
  52 .Fa y/ Ns Ar x ,
  53 using the signs of both arguments to determine the quadrant of
  54 the return value.
  55 .Sh RETURN VALUES
  56 The
  57 .Fn atan2
  58 and the
  59 .Fn atan2f
  60 functions, if successful,
  61 return the arc tangent of
  62 .Fa y/ Ns Ar x
  63 in the range
  64 .Bk -words
  65 .Bq \&- Ns \*(Pi , \&+ Ns \*(Pi
  66 .Ek
  67 radians.
  68 Here are some of the special cases:
  69 .Bl -column atan_(y,x)_:=____  sign(y)_(Pi_atan2(Xy_xX))___
  70 .It Fn atan2 y x No := Ta
  71 .Fn atan y/x Ta
  72 if
  73 .Ar x
  74 > 0,
  75 .It Ta sign( Ns Ar y Ns )*(\*(Pi -
  76 .Fn atan "\\*(Bay/x\\*(Ba" ) Ta
  77 if
  78 .Ar x
  79 < 0,
  80 .It Ta
  81 .No 0 Ta
  82 if x = y = 0, or
  83 .It Ta
  84 .Pf sign( Ar y Ns )*\\*(Pi/2 Ta
  85 if
  86 .Ar x
  87 = 0 \(!=
  88 .Ar y .
  89 .El
  90 .Sh NOTES
  91 The function
  92 .Fn atan2
  93 defines "if x > 0,"
  94 .Fn atan2 0 0
  95 = 0 despite that previously
  96 .Fn atan2 0 0
  97 may have generated an error message.
  98 The reasons for assigning a value to
  99 .Fn atan2 0 0
 100 are these:
 101 .Bl -enum -offset indent
 102 .It
 103 Programs that test arguments to avoid computing
 104 .Fn atan2 0 0
 105 must be indifferent to its value.
 106 Programs that require it to be invalid are vulnerable
 107 to diverse reactions to that invalidity on diverse computer systems.
 108 .It
 109 The
 110 .Fn atan2
 111 function is used mostly to convert from rectangular (x,y)
 112 to polar
 113 .if n\
 114 (r,theta)
 115 .if t\
 116 (r,\(*h)
 117 coordinates that must satisfy x =
 118 .if n\
 119 r\(**cos theta
 120 .if t\
 121 r\(**cos\(*h
 122 and y =
 123 .if n\
 124 r\(**sin theta.
 125 .if t\
 126 r\(**sin\(*h.
 127 These equations are satisfied when (x=0,y=0)
 128 is mapped to
 129 .if n \
 130 (r=0,theta=0).
 131 .if t \
 132 (r=0,\(*h=0).
 133 In general, conversions to polar coordinates
 134 should be computed thus:
 135 .Bd -unfilled -offset indent
 136 .if n \{\
 137 r       := hypot(x,y);  ... := sqrt(x\(**x+y\(**y)
 138 theta   := atan2(y,x).
 139 .\}
 140 .if t \{\
 141 r       := hypot(x,y);  ... := \(sr(x\u\s82\s10\d+y\u\s82\s10\d)
 142 \(*h    := atan2(y,x).
 143 .\}
 144 .Ed
 145 .It
 146 The foregoing formulas need not be altered to cope in a
 147 reasonable way with signed zeros and infinities
 148 on a machine that conforms to
 149 .Tn IEEE 754 ;
 150 the versions of
 151 .Xr hypot 3
 152 and
 153 .Fn atan2
 154 provided for
 155 such a machine are designed to handle all cases.
 156 That is why
 157 .Fn atan2 \(+-0 \-0
 158 = \(+-\*(Pi
 159 for instance.
 160 In general the formulas above are equivalent to these:
 161 .Bd -unfilled -offset indent
 162 .if n \
 163 r := sqrt(x\(**x+y\(**y); if r = 0 then x := copysign(1,x);
 164 .if t \
 165 r := \(sr(x\(**x+y\(**y);\0\0if r = 0 then x := copysign(1,x);
 166 .Ed
 167 .El
 168 .Sh SEE ALSO
 169 .Xr acos 3 ,
 170 .Xr asin 3 ,
 171 .Xr atan 3 ,
 172 .Xr cos 3 ,
 173 .Xr cosh 3 ,
 174 .Xr math 3 ,
 175 .Xr sin 3 ,
 176 .Xr sinh 3 ,
 177 .Xr tan 3 ,
 178 .Xr tanh 3
 179 .Sh STANDARDS
 180 The
 181 .Fn atan2
 182 function conforms to
 183 .St -isoC .