xref: /freebsd/lib/msun/man/lgamma.3 (revision 608da65de9552d5678c1000776ed69da04a45983)
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.\"
30.Dd December 8, 2017
31.Dt LGAMMA 3
32.Os
33.Sh NAME
34.Nm lgamma ,
35.Nm lgamma_r ,
36.Nm lgammaf ,
37.Nm lgammaf_r ,
38.Nm lgammal ,
39.Nm lgammal_r ,
40.Nm gamma ,
41.Nm gamma_r ,
42.Nm gammaf ,
43.Nm gammaf_r ,
44.Nm tgamma ,
45.Nm tgammaf ,
46.Nm tgammal ,
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.Ft "long double"
80.Fn tgammal "long double x"
81.Sh DESCRIPTION
82.Fn lgamma x ,
83.Fn lgammaf x ,
84and
85.Fn lgammal x
86.if t \{\
87return ln\||\(*G(x)| where
88.Bd -unfilled -offset indent
89\(*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
90\(*G(x) = \(*p/(\(*G(1\-x)\|sin(\(*px))	for x < 1.
91.Ed
92.\}
93.if n \
94return ln\||\(*G(x)|.
95The external integer
96.Fa signgam
97returns the sign of \(*G(x).
98.Pp
99.Fn lgamma_r x signgamp ,
100.Fn lgammaf_r x signgamp ,
101and
102.Fn lgammal_r x signgamp
103provide the same functionality as
104.Fn lgamma x ,
105.Fn lgammaf x ,
106and
107.Fn lgammal x ,
108but the caller must provide an integer to store the sign of \(*G(x).
109.Pp
110The
111.Fn tgamma x ,
112.Fn tgammaf x ,
113and
114.Fn tgammal x
115functions return \(*G(x), with no effect on
116.Fa signgam .
117.Pp
118.Fn gamma ,
119.Fn gammaf ,
120.Fn gamma_r ,
121and
122.Fn gammaf_r
123are deprecated aliases for
124.Fn lgamma ,
125.Fn lgammaf ,
126.Fn lgamma_r ,
127and
128.Fn lgammaf_r ,
129respectively.
130.Sh IDIOSYNCRASIES
131Do not use the expression
132.Dq Li signgam\(**exp(lgamma(x))
133to compute g := \(*G(x).
134Instead use a program like this (in C):
135.Bd -literal -offset indent
136lg = lgamma(x); g = signgam\(**exp(lg);
137.Ed
138.Pp
139Only after
140.Fn lgamma
141or
142.Fn lgammaf
143has returned can signgam be correct.
144.Pp
145For arguments in its range,
146.Fn tgamma
147is preferred, as for positive arguments
148it is accurate to within one unit in the last place.
149Exponentiation of
150.Fn lgamma
151will lose up to 10 significant bits.
152.Sh RETURN VALUES
153.Fn gamma ,
154.Fn gammaf ,
155.Fn gammal ,
156.Fn gamma_r ,
157.Fn gammaf_r ,
158.Fn gammal_r ,
159.Fn lgamma ,
160.Fn lgammaf ,
161.Fn lgammal ,
162.Fn lgamma_r ,
163.Fn lgammaf_r ,
164and
165.Fn lgammal_r
166return appropriate values unless an argument is out of range.
167Overflow will occur for sufficiently large positive values, and
168non-positive integers.
169For large non-integer negative values,
170.Fn tgamma
171will underflow.
172.Sh BUGS
173To conform with newer C/C++ standards, a stub implementation for
174.Nm tgammal
175was committed to the math library, where
176.Nm tgammal
177is mapped to
178.Nm tgamma .
179Thus, the numerical accuracy is at most that of the 53-bit double
180precision implementation.
181.Sh SEE ALSO
182.Xr math 3
183.Sh STANDARDS
184The
185.Fn lgamma ,
186.Fn lgammaf ,
187.Fn lgammal ,
188.Fn tgamma ,
189.Fn tgammaf ,
190and
191.Fn tgammal
192functions are expected to conform to
193.St -isoC-99 .
194.Sh HISTORY
195The
196.Fn lgamma
197function appeared in
198.Bx 4.3 .
199The
200.Fn gamma
201function appeared in
202.Bx 4.4
203as a function which computed \(*G(x).
204This version was used in
205.Fx 1.1 .
206The name
207.Fn gamma
208was originally dedicated to the
209.Fn lgamma
210function,
211and that usage was restored by switching to Sun's fdlibm in
212.Fx 1.1.5 .
213The
214.Fn tgamma
215function appeared in
216.Fx 5.0 .
217