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