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