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