1.\" Copyright (c) 1985, 1991 Regents of the University of California.
2.\" All rights reserved.
3.\"
4.\" %sccs.include.redist.roff%
5.\"
6.\"     @(#)lgamma.3	6.5 (Berkeley) 07/31/91
7.\"
8.Dd
9.Dt LGAMMA 3
10.Os BSD 4.3
11.Sh NAME
12.Nm lgamma
13.Nd log gamma function
14.Sh SYNOPSIS
15.Fd #include <math.h>
16.Ft double
17.Fn lgamma "double x"
18.Sh DESCRIPTION
19.ta \w'Lgamma returns ln\||\(*G(x)| where'u+1n +1.7i
20.if t \{\
21Lgamma returns ln\||\(*G(x)| where
22.Bd -unfilled -offset indent
23\(*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
24.br
25\(*G(x) = \(*p/(\(*G(1\-x)\|sin(\(*px))	for x < 1.
26.Ed
27.\}
28.if n \
29Lgamma returns ln\||\(*G(x)|.
30.ta
31.Pp
32The external integer
33.Fa signgam
34returns the sign of
35\(*G(x) .
36.Sh IDIOSYNCRASIES
37Do
38.Em not
39use the expression
40.Dq Li signgam\(**exp(lgamma(x))
41to compute g := \(*G(x).  Instead use a program like this (in C):
42.Bd -literal -offset indent
43lg = lgamma(x); g = signgam\(**exp(lg);
44.Ed
45.Pp
46Only after
47.Fn lgamma
48has returned can signgam be correct.
49Note too that \(*G(x) must overflow when x is large enough,
50underflow when \-x is large enough, and spawn a division by zero
51when x is a nonpositive integer.
52.Pp
53Only in the
54.Tn UNIX
55math library for C was the name gamma ever attached
56to ln\(*G.  Elsewhere, for instance in
57.Tn IBM Ns 's
58.Tn FORTRAN
59library, the name
60.Tn GAMMA
61belongs to \(*G and the name
62.Tn ALGAMA
63to ln\(*G in single precision;
64in double the names are
65.Tn DGAMMA
66and
67.Tn DLGAMA .
68Why should C be different?
69.Pp
70Archaeological records suggest that C's
71.Em gamma
72originally delivered
73ln(\(*G(|x|)).  Later, the program gamma was changed to
74cope with negative arguments x in a more conventional way, but
75the documentation did not reflect that change correctly.  The most
76recent change corrects inaccurate values when x is almost a
77negative integer, and lets \(*G(x) be computed without
78conditional expressions.  Programmers should not assume that
79.Fn lgamma
80has settled down.
81.Pp
82At some time in the future, the name
83.Em gamma
84will be rehabilitated
85and used for the gamma function, just as is done in
86.Tn FORTRAN .
87The reason for this is not so much compatibility with
88.Tn FORTRAN
89as a
90desire to achieve greater speed for smaller values of |x| and greater
91accuracy for larger values.
92.Pp
93Meanwhile, programmers who have to use the name
94.Em gamma
95in its former
96sense, for what is now
97.Fn lgamma ,
98have two choices:
99.Bl -enum -width indent
100.It
101Use the old math library,
102.Pa libom .
103.It
104Add the following program to your others:
105.Bd -literal -offset indent
106#include <math.h>
107double gamma(x)
108double x;
109{
110	return (lgamma(x));
111}
112.Ed
113.El
114.Sh DIAGNOSTICS
115The reserved operand is returned on a
116.Tn VAX
117for negative integer arguments,
118.Va errno
119is set to
120.Er ERANGE ;
121for very large arguments over/underflows will
122occur inside the
123.Fn lgamma
124routine.
125.Sh SEE ALSO
126.Xr math 3 ,
127.Xr infnan 3
128.Sh HISTORY
129The
130.Nm
131function appeared in
132.Bx 4.3 .
133