libm: Sync with FreeBSD (gains 6 long double functions)
[dragonfly.git] / lib / libm / man / lgamma.3
1 .\" Copyright (c) 1985, 1991 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 .\" 3. 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: @(#)lgamma.3      6.6 (Berkeley) 12/3/92
29 .\" $FreeBSD: head/lib/msun/man/lgamma.3 176388 2008-02-18 17:27:11Z das $
30 .\"
31 .Dd September 12, 2014
32 .Dt LGAMMA 3
33 .Os
34 .Sh NAME
35 .Nm lgamma ,
36 .Nm lgamma_r ,
37 .Nm lgammaf ,
38 .Nm lgammaf_r ,
39 .Nm lgammal ,
40 .Nm lgammal_r ,
41 .Nm gamma ,
42 .Nm gamma_r ,
43 .Nm gammaf ,
44 .Nm gammaf_r ,
45 .Nm tgamma ,
46 .Nm tgammaf
47 .Nd log gamma functions, gamma function
48 .Sh LIBRARY
49 .Lb libm
50 .Sh SYNOPSIS
51 .In math.h
52 .Ft extern int
53 .Fa signgam ;
54 .sp
55 .Ft double
56 .Fn lgamma "double x"
57 .Ft double
58 .Fn lgamma_r "double x" "int *signgamp"
59 .Ft float
60 .Fn lgammaf "float x"
61 .Ft float
62 .Fn lgammaf_r "float x" "int *signgamp"
63 .Ft "long double"
64 .Fn lgammal "long double x"
65 .Ft "long double"
66 .Fn lgammal_r "long double x" "int *signgamp"
67 .Ft double
68 .Fn gamma "double x"
69 .Ft double
70 .Fn gamma_r "double x" "int *signgamp"
71 .Ft float
72 .Fn gammaf "float x"
73 .Ft float
74 .Fn gammaf_r "float x" "int *signgamp"
75 .Ft "long double"
76 .Fn tgamma "double x"
77 .Ft float
78 .Fn tgammaf "float x"
79 .Sh DESCRIPTION
80 .Fn lgamma x ,
81 .Fn lgammaf x ,
82 and
83 .Fn lgammal x
84 .if t \{\
85 return ln\||\(*G(x)| where
86 .Bd -unfilled -offset indent
87 \(*G(x) = \(is\d\s8\z0\s10\u\u\s8\(if\s10\d t\u\s8x\-1\s10\d e\u\s8\-t\s10\d dt for x > 0 and
88 \(*G(x) = \(*p/(\(*G(1\-x)\|sin(\(*px)) for x < 1.
89 .Ed
90 .\}
91 .if n \
92 return ln\||\(*G(x)|.
93 The external integer
94 .Fa signgam
95 returns the sign of \(*G(x).
96 .Pp
97 .Fn lgamma_r x signgamp ,
98 .Fn lgammaf_r x signgamp ,
99 and
100 .Fn lgammal_r x signgamp
101 provide the same functionality as
102 .Fn lgamma x , 
103 .Fn lgammaf x ,
104 and
105 .Fn lgammal x ,
106 but the caller must provide an integer to store the sign of \(*G(x).
107 .Pp
108 The
109 .Fn tgamma x
110 and
111 .Fn tgammaf x
112 functions return \(*G(x), with no effect on
113 .Fa signgam .
114 .Pp
115 .Fn gamma ,
116 .Fn gammaf ,
117 .Fn gamma_r ,
118 and
119 .Fn gammaf_r
120 are deprecated aliases for
121 .Fn lgamma ,
122 .Fn lgammaf ,
123 .Fn lgamma_r ,
124 and
125 .Fn lgammaf_r ,
126 respectively.
127
128 .Sh IDIOSYNCRASIES
129 Do not use the expression
130 .Dq Li signgam\(**exp(lgamma(x))
131 to compute g := \(*G(x).
132 Instead use a program like this (in C):
133 .Bd -literal -offset indent
134 lg = lgamma(x); g = signgam\(**exp(lg);
135 .Ed
136 .Pp
137 Only after
138 .Fn lgamma
139 or
140 .Fn lgammaf
141 has returned can signgam be correct.
142 .Pp
143 For arguments in its range,
144 .Fn tgamma
145 is preferred, as for positive arguments
146 it is accurate to within one unit in the last place.
147 Exponentiation of
148 .Fn lgamma
149 will lose up to 10 significant bits.
150 .Sh RETURN VALUES
151 .Fn gamma ,
152 .Fn gammaf ,
153 .Fn gammal ,
154 .Fn gamma_r ,
155 .Fn gammaf_r ,
156 .Fn gammal_r ,
157 .Fn lgamma ,
158 .Fn lgammaf ,
159 .Fn lgammal ,
160 .Fn lgamma_r ,
161 .Fn lgammaf_r ,
162 and
163 .Fn lgammal_r
164 return appropriate values unless an argument is out of range.
165 Overflow will occur for sufficiently large positive values, and
166 non-positive integers.
167 For large non-integer negative values,
168 .Fn tgamma
169 will underflow.
170 .Sh SEE ALSO
171 .Xr math 3
172 .Sh STANDARDS
173 The
174 .Fn lgamma ,
175 .Fn lgammaf ,
176 .Fn lgammal ,
177 .Fn tgamma ,
178 and
179 .Fn tgammaf
180 functions are expected to conform to
181 .St -isoC-99 .
182 .Sh HISTORY
183 The
184 .Fn lgamma
185 function appeared in
186 .Bx 4.3 .
187 The
188 .Fn gamma
189 function appeared in
190 .Bx 4.4
191 as a function which computed \(*G(x).
192 This version was used in
193 .Fx 1.1 .
194 The name
195 .Fn gamma
196 was originally dedicated to the
197 .Fn lgamma
198 function,
199 and that usage was restored by switching to Sun's fdlibm in
200 .Fx 1.1.5 .
201 The
202 .Fn tgamma
203 function appeared in
204 .Dx 2.13 .