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 .Sh IDIOSYNCRASIES
 128 Do not use the expression
 129 .Dq Li signgam\(**exp(lgamma(x))
 130 to compute g := \(*G(x).
 131 Instead use a program like this (in C):
 132 .Bd -literal -offset indent
 133 lg = lgamma(x); g = signgam\(**exp(lg);
 134 .Ed
 135 .Pp
 136 Only after
 137 .Fn lgamma
 138 or
 139 .Fn lgammaf
 140 has returned can signgam be correct.
 141 .Pp
 142 For arguments in its range,
 143 .Fn tgamma
 144 is preferred, as for positive arguments
 145 it is accurate to within one unit in the last place.
 146 Exponentiation of
 147 .Fn lgamma
 148 will lose up to 10 significant bits.
 149 .Sh RETURN VALUES
 150 .Fn gamma ,
 151 .Fn gammaf ,
 152 .Fn gamma_r ,
 153 .Fn gammaf_r ,
 154 .Fn lgamma ,
 155 .Fn lgammaf ,
 156 .Fn lgammal ,
 157 .Fn lgamma_r ,
 158 .Fn lgammaf_r ,
 159 and
 160 .Fn lgammal_r
 161 return appropriate values unless an argument is out of range.
 162 Overflow will occur for sufficiently large positive values, and
 163 non-positive integers.
 164 For large non-integer negative values,
 165 .Fn tgamma
 166 will underflow.
 167 .Sh SEE ALSO
 168 .Xr math 3
 169 .Sh STANDARDS
 170 The
 171 .Fn lgamma ,
 172 .Fn lgammaf ,
 173 .Fn lgammal ,
 174 .Fn tgamma ,
 175 and
 176 .Fn tgammaf
 177 functions are expected to conform to
 178 .St -isoC-99 .
 179 .Sh HISTORY
 180 The
 181 .Fn lgamma
 182 function appeared in
 183 .Bx 4.3 .
 184 The
 185 .Fn gamma
 186 function appeared in
 187 .Bx 4.4
 188 as a function which computed \(*G(x).
 189 This version was used in
 190 .Fx 1.1 .
 191 The name
 192 .Fn gamma
 193 was originally dedicated to the
 194 .Fn lgamma
 195 function,
 196 and that usage was restored by switching to Sun's fdlibm in
 197 .Fx 1.1.5 .
 198 The
 199 .Fn tgamma
 200 function appeared in
 201 .Dx 2.13 .