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