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